Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

xpc_main(3)              BSD Library Functions Manual              xpc_main(3)

NAME
     xpc_main -- XPC service runtime

SYNOPSIS
     #include <xpc/xpc.h>

     void
     xpc_main(xpc_connection_handler_t handler);

     void
     xpc_transaction_begin(void);

     void
     xpc_transaction_end(void);

DESCRIPTION
     The xpc_main() function is called by an XPC service to initialize the runtime and start listening for
     incoming connections.

HANDLER
     The handler provided to xpc_main() will be invoked when a new connection has been established with the
     service.  For each new connection, an xpc_connection_t will be passed as the parameter to the handler.
     Each connection corresponds to a call to xpc_connection_create(3) made by a client of the service.

     The service is responsible for setting an event handler on the new connection and resuming it in the
     same fashion as new connections returned by xpc_connection_create(3).

     Important: The new connection passed to handler() must be retained using xpc_retain(3) if it will be
     stored in data structures that persist beyond the scope of that function.

           static void
           new_connection_handler(xpc_connection_t peer)
           {
                   xpc_connection_set_event_handler(peer, ^(xpc_object_t event) {
                           // Handle messages and errors.
                   });
                   xpc_connection_resume(peer);
           }

           int
           main(void)
           {
                   xpc_main(new_connection_handler);
                   exit(EXIT_FAILURE);
           }

     launchd jobs which advertise MachServices may not call xpc_main().

RUNTIME MANAGEMENT
     The XPC runtime automatically keeps track of message activity to determine whether a service is busy or
     idle. If the service remains idle after a period of inactivity (defined by the system), xpc_main() will
     exit the process.

     Activity is tracked with a transaction count maintained by the XPC runtime.  A service is deemed idle
     when its transaction count is zero.  The transaction count is incremented immediately before the
     receipt and delivery of a message to a peer connection's event handler. The transaction count is corre-spondingly correspondingly
     spondingly decremented when the event handler returns.

     The transaction count is also incremented when a reply message is created with
     xpc_dictionary_create_reply(3), and decremented when the reply is sent. As a result, a service with
     outstanding reply messages is not considered idle.

     Services may extend the default behavior using xpc_transaction_begin() and xpc_transaction_end(), which
     increment and decrement the transaction count respectivley. This may be necessary for services that
     send periodic messages to their clients, not in direct reply to a received message.

     If the service has a non-zero transaction count at a time when the system deems it necessary to termi-nate terminate
     nate the service, all peer connections in the service will receive the XPC_ERROR_TERMINATION_IMMINENT
     event. This event indicates that the service should unwind all outstanding work as quickly as possible
     and not begin any new work, as the system will terminate the process if it does not exit in a timely
     fashion. After this event is received, no further messages will be delivered to the peers, and the end
     of the service's last outstanding transaction will automatically terminate the process.

     Important: xpc_transaction_begin() and xpc_transaction_end() are not safe to call before xpc_main().
     In general, an XPC service's main() should have no other code in it other than a call to xpc_main()
     followed by a call to exit(2) as illustrated above.

     The XPC runtime will also automatically manage the service's priority based on where a message came
     from. If an app sends a message to the service, the act of sending that message will boost the destina-tion destination
     tion service's priority and resource limits so that it can more quickly fill the request. If, however,
     a service gets a message from a background process, the service stays at a lower priority so as not to
     interfere with work initiated as a direct result of user interaction.

     The lifetime of these boosts is tied to the lifetime of the message or reply object, just like transac-tions. transactions.
     tions. So while the service maintains a reference to a message which boosted it, the boost will remain.
     If a reply message is created using xpc_dictionary_create_reply(3), the boost transfers to the reply
     object and will remain with the process until until the reply has been sent or deallocated.

     Note that boosts happen as a result of a message-send operation. So even if the service isn't running
     when a boosting message is sent, it will be launched on-demand at the elevated priority necessary to
     receive the message in a timely fashion.

     launchd jobs which use XPC for their IPC may opt into priority boosting by specifying their ProcessType
     as Adaptive. This will apply priority boosting behavior only to the MachServices that are in the
     launchd.plist. See launchd.plist(5) for more details.

DEFAULT ENVIRONMENT
     The execution environment for XPC services bundled with applications is tightly controlled. By default,
     services are executed in a new security audit session and therefore do not have access to the current
     user's keychain or the ability to draw UI.  This behavior may be overridden with the
     JoinExistingSession key in the service's Info.plist.

     By default, the xpc_main() function will call the dispatch_main(3) function to manage the service's
     main event loop.  This behavior may be overridden with the RunLoopType key in the service's Info.plist.

     See xpcservice.plist(5) for more information about these keys.

SEE ALSO
     xpc(3), xpc_connection_create(3)

Darwin                           1 July, 2011                           Darwin