[Note: The GPEC interface manpages of PSARC/2002/321 were withdrawn by PSARC/2004/398. The following manpage should not go into Solaris - it is just provided to match the previous set.] NAME sysevent_evc_xsubscribe, sysevent_subattr_alloc, sysevent_subattr_free, sysevent_subattr_thrattr, sysevent_subattr_thrmin, sysevent_subattr_thrmax, sysevent_subattr_thrcreate, sysevent_subattr_thrsetup - subscribe to an event channel, with control over delivery semantics SYNOPSIS cc [flag ...] file ... -lsysevent [library ...] #include sysevent_subattr_t *sysevent_subattr_alloc(void); void sysevent_subattr_free(sysevent_subattr_t *attr); int sysevent_subattr_thrattr(sysevent_subattr_t *, pthread_attr_t *); int sysevent_subattr_thrmin(sysevent_subattr_t *, int); int sysevent_subattr_thrmax(sysevent_subattr_t *, int); void sysevent_subattr_thrcreate(sysevent_subattr_t *, door_xcreate_server_func_t *, void *); void sysevent_subattr_thrsetup(sysevent_subattr_t *, door_xcreate_thrsetup_func_t *, void *); int sysevent_evc_xsubscribe(evchan_t *scp, const char *sid, const char *classpat, int (*callbackfunc)(sysevent_t *ev, void *cookie), void *cookie, uint32_t flags, sysevent_subattr_t *attr); DESCRIPTION The sysevent_evc_xsubscribe function is a sibling to sysevent_evc_subscribe. There is a single additional argument to provide control over a number of attributes of the subscription, primarily of the threads created to perform subscription delivery callbacks. For both sysevent_evc_subscribe and sysevent_evc_xsubscribe, callbacks for matching subscriptions are performed as door invocations. A new door is created for each successful call to sysevent_evc_subscribe or sysevent_evc_xsubscribe. For sysevent_evc_subscribe the doors used for delivery callbacks are non-private doors - created with door_create(3C) without DOOR_PRIVATE. There is little control over the creation of door service threads or their characteristics. Door server threads can service an invocation of any non-private door, and a new service thread is created whenever a new invocation (event delivery) finds all existing door service threads already active. With sysevent_evc_xsubscribe the delivery callback doors are created with door_xcreate(3C). In many ways sysevent_evc_xsubscribe is to sysevent_evc_subscribe what door_xcreate(3C) is to door_create(3C). The first six arguments to sysevent_evc_xsubscribe are as for sysevent_evc_subscribe, with identical semantics. This includes the ablity to use simple wildcarding in the class names subscribed to, such as "list.*". All matching subscriptions to an event receive a delivery callback, thus if subscriptions to both "foo.*" and "foo.bar" have been established then an event of class "foo.bar" will result in a delivery callback for both subscriptions. The final argument to sysevent_evc_xsubscribe is a pointer to an opaque sysevent_subattr_t structure. This may be NULL to accept default attributes, or allocated using sysevent_subattr_alloc and further configured as desired using the other sysevent_subattr_* functions described below. Note that sysevent_evc_xsubscribe with a NULL sysevent_subattr_t pointer is not equivalent to sysevent_evc_subscribe - the former still uses a private door for each subscription request. Subscription Attributes A new sysevent_evc_xsubscribe attribute object is allocated using sysevent_subattr_alloc. The same attribute object may be shared by multiple subscriptions (even on distinct channel bindings). The attribute object may be freed after the call to sysevent_evc_xsubscribe since attributes are duplicated during that call. Attributes allocated using sysevent_subattr_alloc are initialized and valid for immediate use. The default attributes thus obtained use the standard thread creation semantics described below, with each subscription resulting in a single new thread dedicated to serving the associated door and no maximum imposed. These are the semantics obtained through using a NULL sysevent_subattr_t pointer. Default door server creation semantics If you do not select a new door_xcreate_server_func_t using sysevent_subattr_thrcreate then a default door server creation function applies. This: - creates the door as a private door with the initial number of threads requested via sysevent_subattr_thrmin (or 1 if sysevent_subattr_thrmin was never applied to the attributes object) - will not create door server threads for this door in excess of the maximum imposed by sysevent_subattr_thrmax; a value of 0 (the default) imposes no maximum - uses any thread setup function appointed via sysevent_subattr_thrsetup; the default applies only the minimum setup required by door_xcreate(3C) - uses any thread attributes chosen with sysevent_subattr_thrattr, otherwise applies the minimum required by door_xcreate(3C) which is for PTHREAD_CREATE_DETACHED and PTHREAD_SCOPE_SYSTEM - creates new threads using pthread_create(3C) with a signal mask as chosen via sysevent_subattr_sigmask, or a default that masks all signal save for SIGABRT Initial number of private server threads to create: sysevent_subattr_thrmin The function sysevent_subattr_thrmin configures the attributes to specify the number of threads bound to the new door when the new subscription is established. This attribute is applied for both custom and default door server creation semantics. All threads must be successfully created and bound to the new door, or the subscription attempt fails. sysevent_subattr_thrmin returns 0 on success. It returns EINVAL if the requested minimum is less than one or if non-default thread creation semantics have been selected for the attributes (i.e., sysevent_subattr_thrcreate applied). Maximum server threads for this subscription: sysevent_subattr_thrmax The function sysevent_subattr_thrmax configures the attributes to specify the maximum number of threads that can be created to service this subscription. This attribute is only applied when default door server thread creation semantics are in use - if a custom function is selected with sysevent_subattr_thrcreate then this attribute is ignored. When a subscription delivery door invocation is received on the last available thread for the door (others all busy servicing other invocations) then we will create an additional server thread if that will not exceed the given maximum number of threads. A value of zero means "no maximum". You may configure the minimum and maximum limits in the attributes in any order, but at the time the attributes are used in a sysevent_evc_xsubscribe call the values must be legal: the minimum may not exceed the maximum unless the latter is zero (meaning no maximum), and in all cases the minimum must be at least 1. sysevent_subattr_thrmax returns 0 on success. It returns EINVAL if non-default thread creation semantics have been selected for the attributes. Attributes for pthread_create: sysevent_subattr_thrattr This only applies if default thread creation semantics are in effect. The chosen pthread_attr_t are used in calls to pthread_create to create door service threads. At minimum these attributes should be initialized PTHREAD_CREATE_DETACHED and PTHREAD_SCOPE_SYSTEM. Do not pthread_attr_destroy the pthread_attr_t until all subscriptions using it have been dropped. Door server thread setup function: sysevent_subattr_thrsetup This fulfils the role of a door_xcreate_thrsetup_func_t as described in door_xcreate(3C) - the nominated function is used in setting up newly-created door server threads, and the requested cookie passed to it. A door server thread setup function can be appointed for use with both default and custom server thread creation semantics. A custom thread setup function must setup threads with at least pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL) and pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, NULL). If the application is truly interested in aborted door client calls then you can setup for thread cancellation. A thread setup function runs in the context of the newly-created thread before it enters door service, so this is a suitable place to perform any pthread_setspecific activity that is desired. Door server thread creation function: sysevent_subattr_thrcreate If the default door server creation semantics described above do not offer sufficient flexibility then it is possible to provide an alternative door server thread creation function as per door_xcreate(3C). A custom function must create new threads that are PTHREAD_CREATE_DETACHED and PTHREAD_SCOPE_SYSTEM, as described in door_xcreate(3C). Of the attribute functions, only sysevent_subattr_thrmin and sysevent_subattr_thrcreate have any effect when a custom door server creation function is selected. The requested mininum/initial number of threads are created to service this subscription. Restrictions on actions that may be performed from callback context The following apply in callback context: 1) A callback function must not call sysevent_evc_unbind to unbind from the channel for which this callback is active; such a call will fail with EDEADLK. 2) A callback function must not call sysevent_evc_unsubscribe for any subscription on the channel for which this callback is active; such a call will fail with EDEADLK. 3) If default server create semantics are in use then a callback must not call door_unbind(3C) or cause the thread to exit with pthread_exit(3C) or thr_exit(3C). sysevent_evc_unsubscribe behaviour If a subscription was established with sysevent_evc_xsubscribe then when it is dropped using sysevent_evc_unsubscribe the door service threads bound to the associated door will all be made to exit before the door is revoked. This is different to subscriptions established with sysevent_evc_subscribe in which the door server threads will remain dormant even after successful sysevent_evc_unsubscribe. If you have used a custom thread setup function to associate thread-specific data with door service threads then any destructor functions nominated in pthread_key_create will be called on thread exit, as usual. ATTRIBUTES See attributes(5) for descriptionsof the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Architecture | all | |_____________________________|_____________________________| | Availability | SUNWcsl | |_____________________________|_____________________________| | Interface Stability | Consolidation Private | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________|