xpc_object(3) BSD Library Functions Manual xpc_object(3)
xpc_object -- XPC object protocol
XPC objects share functions for coordinating memory management, type checking, comparing for equality, and hashing.
Objects returned by creation functions in the XPC framework may be uniformly retained and released with the functions xpc_retain() and
The XPC framework does not guarantee that any given client has the last or only reference to a given object. Objects may be retained inter-
nally by the system.
Functions which return objects follow the conventional create, copy and get naming rules:
o create A new object with a single reference is returned. This reference should be released by the caller.
o copy A copy or retained object reference is returned. This reference should be released by the caller.
o get An unretained reference to an existing object is returned. The caller must not release this reference, and is responsible for
retaining the object for later use if necessary.
INTEGRATION WITH OBJECTIVE-C
When building with an Objective-C or Objective-C++ compiler, XPC objects are declared as Objective-C types. This results in the follow-
ing differences compared to building as plain C/C++:
- if Objective-C Automated Reference Counting is enabled, XPC objects are memory managed by the Objective-C runtime and explicit
calls to the xpc_retain() and xpc_release() functions will produce build errors.
Note: when ARC is enabled, care needs to be taken with XPC API returning an interior pointer that is only valid as long as an asso-
ciated object has not been released. If that object is held in a variable with automatic storage, it may need to be annotated with
the objc_precise_lifetime attribute, or stored in a __strong instance variable instead, to ensure that the object is not prema-
turely released. The functions returning interior pointers are:
o xpc_data_get_bytes_ptr(3), xpc_string_get_string_ptr(3), xpc_uuid_get_bytes(3)
o xpc_array_get_data(3), xpc_array_get_string(3), xpc_array_get_uuid(3)
o xpc_dictionary_get_data(3), xpc_dictionary_get_string(3), xpc_dictionary_get_uuid(3)
- the Blocks runtime automatically retains and releases XPC objects captured by blocks upon Block_copy() and Block_release(), e.g. as
performed during asynchronous execution of a block via dispatch_async(3).
Note: retain cycles may be encountered if XPC connection objects are captured by their handler blocks; these cycles can be broken
by declaring the captured object __weak or by calling xpc_connection_cancel(3) to cause its handler blocks to be released explic-
- XPC objects can be added directly to Cocoa collections, and their lifetime is tracked by the Objective-C static analyzer.
Integration of XPC objects with Objective-C requires targeting Mac OS X 10.8 or later, and is disabled when building with Objective-C
Garbage Collection or for the legacy Objective-C runtime. It can also be disabled manually by using compiler options to define the
OS_OBJECT_USE_OBJC preprocessor macro to 0.
Important: When building with a plain C/C++ compiler or when integration with Objective-C is disabled, XPC objects are not automatically
retained and released when captured by a block. Therefore, when a XPC object is captured by a block that will be executed asynchronously, the
object must be manually retained and released:
The xpc_get_type() function returns the type of an XPC object as a pointer of type xpc_type t. The returned type may be compared against the
type constants defined by the XPC framework with simple pointer equality.
BOXED OBJECTS AND COLLECTIONS
Most XPC object types are boxed representations of primitive C language types or low-level operating system handles. These boxed objects are
The XPC framework provides two collection types: dictionaries and arrays. These types are mutable and may have boxed objects added or
removed from the collection.
A suite of primitive get and set functions are available for the dictionary and array types. These functions allow for the insertion and
extraction of primitive values from the collection directly, without the need for intermediate boxed objects.
The following is a list of primitive get and set functions for the dictionary collection type:
o xpc_dictionary_set_bool(3), xpc_dictionary_get_bool(3), xpc_array_set_bool(3), xpc_array_get_bool(3)
o xpc_dictionary_set_int64(3), xpc_dictionary_get_int64(3), xpc_array_set_int64(3), xpc_array_get_int64(3)
o xpc_dictionary_set_uint64(3), xpc_dictionary_set_uint64(3), xpc_array_set_uint64(3), xpc_array_get_uint64(3)
o xpc_dictionary_set_double(3), xpc_dictionary_set_double(3), xpc_array_set_double(3), xpc_array_get_double(3)
o xpc_dictionary_set_date(3), xpc_dictionary_set_date(3), xpc_array_set_date(3), xpc_array_get_date(3)
o xpc_dictionary_set_data(3), xpc_dictionary_get_data(3), xpc_array_set_data(3), xpc_array_get_data(3)
o xpc_dictionary_set_string(3), xpc_dictionary_get_string(3), xpc_array_set_string(3), xpc_array_get_string(3)
o xpc_dictionary_set_uuid(3), xpc_dictionary_get_uuid(3), xpc_array_set_uuid(3), xpc_array_get_uuid(3)
o xpc_dictionary_set_fd(3), xpc_dictionary_get_fd(3), xpc_array_set_fd(3), xpc_array_get_fd(3)
o xpc_dictionary_set_connection(3), xpc_dictionary_get_connection(3), xpc_array_set_connection(3), xpc_array_get_connection(3)
When the requested key or index is not present in the collection, or if the value for the requested key or index is not of the expected type,
these functions will return sensible default values:
o bool false
o int64 0
o uint64 0
o double NAN
o date 0
o data NULL
o uuid NULL
o string NULL
o fd -1
o connection NULL
Objects may be copied using the xpc_copy() function. The result of xpc_copy() may or may not be a brand new object (i.e. a different
pointer). The system may choose to return the same object with an additional reference rather than doing a complete copy for efficiency rea-
Two objects may be compared for equality using the xpc_equal() function. Objects must be of the same type as returned by xpc_get_type() in
order to be considered equal. No casting or transformation is performed on the underlyin value in order to determine equality.
Collection types are compared for deep equality, that is to say, two arrays are equal only if they contain the same values in the same order,
and two dictionaries are equal only if they contain the same values for the same keys.
Important: File descriptors and shared memory objects cannot be reliably compared for equality, and therefore the xpc_equal() function will
only perform a simple pointer-equality check for these objects.
Objects may be hashed using the xpc_hash() function. The result of the hash function is guaranteed to be identical for objects which compare
to be equal using xpc_equal().
Important: The hash value for a given object should not be considered portable across multiple processes or releases of the operating system
and as a result should not be stored in a permanent fashion.
The xpc_copy_description() function may be used to produce a human-readable description of an object. The returned C-string must be freed by
the caller using free(3).
Important: The format of this description is not guaranteed to remain consistent across releases, and the output should only be used for
dispatch_async(3), xpc_abort(3), xpc_array_create(3), xpc_connection_cancel(3), xpc_connection_create(3), xpc_dictionary_create(3),
Darwin 1 March, 2012 Darwin