xpc_object(3) BSD Library Functions Manual xpc_object(3)
NAME
xpc_object -- XPC object protocol
SYNOPSIS
#include <xpc/xpc.h>
xpc_object_t
xpc_retain(xpc_object_t object);
void
xpc_release(xpc_object_t object);
xpc_type_t
xpc_get_type(xpc_object_t object);
xpc_object_t
xpc_copy(xpc_object_t object);
bool
xpc_equal(xpc_object_t object);
size_t
xpc_hash(xpc_object_t object);
char *
xpc_copy_description(xpc_object_t object);
DESCRIPTION
XPC objects share functions for coordinating memory management, type
checking, comparing for equality, and hashing.
MEMORY MANAGEMENT
Objects returned by creation functions in the XPC framework may be uni-
formly retained and released with the functions xpc_retain() and
xpc_release() respectively.
The XPC framework does not guarantee that any given client has the last
or only reference to a given object. Objects may be retained internally
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 fol-
lowing 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
associated object has not been released. If that object is held
in a variable with automatic storage, it may need to be anno-
tated with the objc_precise_lifetime attribute, or stored in a
__strong instance variable instead, to ensure that the object
is not prematurely 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 execu-
tion 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 explicitly.
- 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 Objec-
tive-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:
xpc_retain(object);
dispatch_async(queue, ^{
do_something_with_object(object);
xpc_release(object);
});
TYPES
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.
Type constants:
o XPC_TYPE_CONNECTION
o XPC_TYPE_ENDPOINT
o XPC_TYPE_NULL
o XPC_TYPE_BOOL
o XPC_TYPE_INT64
o XPC_TYPE_UINT64
o XPC_TYPE_DOUBLE
o XPC_TYPE_DATE
o XPC_TYPE_DATA
o XPC_TYPE_STRING
o XPC_TYPE_UUID
o XPC_TYPE_FD
o XPC_TYPE_SHMEM
o XPC_TYPE_ARRAY
o XPC_TYPE_DICTIONARY
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
immutable.
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 dictio-
nary and array types. These functions allow for the insertion and extrac-
tion 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 dic-
tionary 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
COPYING
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 addi-
tional reference rather than doing a complete copy for efficiency rea-
sons.
EQUALITY
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.
OBJECT DESCRIPTIONS
The xpc_copy_description() function may be used to produce a human-read-
able 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 debug-
ging purposes.
SEE ALSO
dispatch_async(3), xpc_abort(3), xpc_array_create(3),
xpc_connection_cancel(3), xpc_connection_create(3),
xpc_dictionary_create(3), xpc_endpoint_create(3), xpc_objects(3)
Darwin 1 March, 2012 Darwin
Mac OS X 10.8 - Generated Sat Aug 25 19:09:21 CDT 2012