manpagez: man pages & more
man xpc_object(3)
Home | html | info | man
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
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.