1. Introduction 1.1. Project/Component Working Name: GPEC interface changes and additions 1.2. Name of Document Author/Supplier: Gavin Maltby 1.3. Date of This Document: 09/18/2009 1.5. Email Aliases: 1.5.1. Responsible Manager: sridhar.yedunuthula@sun.com 1.5.2. Responsible Engineer: gavin.maltby@sun.com 4. Technical Description: 4.1. Details: The GPEC (general-purpose event channels) interface is Consolidation Private (see 4.5 for a history). This case makes some minor changes to existing aspects of the interface, and adds a new member and associated support functions. All new interfaces are Consolidation Private. a) EVCH_HOLD_PEND_INDEF This new flag to sysevent_evc_bind is a stronger version of EVCH_HOLD_PEND - even if the channel has no remaining bindings it will not be destroyed so long as events remain unconsumed. This is suitable for use with short-lived event producers that may bind to (create) the channel and exit before the intended consumer has started. Use of this flag only really makes sense in userland - the kernel implementation of EVCH_HOLD_PEND has the indefinite semantics already. The introduction of this new flag has no impact on existing GPEC users. b) Subscription Wildcarding The event class argument to sysevent_evc_subscribe may now be wildcarded with simple wildcarding ('*') characters. A maximum of 10 wildcard characters in the class pattern is permitted, and the call to sysevent_evc_subscribe returns EINVAL if that limit is exceeded. The semantics of wildcarding are that *all* matching subscriptions (wildcarded or not) will result in event delivery. Thus if a consumer has subscriptions to both "foo.*" and "foo.bar" then an event of class "foo.bar" will result in two delivery callbacks. The new interface sysevent_evc_xsubscribe below also supports this wildcarding. There is no impact to existing users of sysevent_evc_subscribe since no event classes include wildcard characters. c) sysevent_evc_{unbind,unsubscribe} now return int Old: void sysevent_evc_unsubscribe(evchan_t *, const char *); New: int sysevent_evc_unsubscribe(evchan_t *, const char *); This interface now returns 0 on success, otherwise one of: EINVAL Argument for opaque channel handle is invalid. Argument for subscriber id is NULL, a zero length string, or exceeds MAX_SUBID_LEN. An attempt to unsubscribe from a channel that was closed on exec. EDEADLK The attempt to unsubscribe was made from within an event delivery callback arising from the target channel. This error return is only possible for subscription initiated with sysevent_evc_xsubscribe (sysevent_evc_subscribe will merrily deadlock). ENXIO A problem occured communicating with the underlying kernel device driver (/dev/sysevent). Old: void sysevent_evc_unbind(evchan_t *); New: int sysevent_evc_unbind(evchan_t *); This interface now returns 0 on success, otherwise one of: EINVAL Argument for opaque channel handle is invalid. EDEADLK If this attempt to unbind is made from within an event delivery callback arising from the target channel. This error return is only possible for subscription initiated with sysevent_evc_xsubscribe. Existing uses outside ON will not break; on recompile there may be a lint warning for a function return value not used. d) Introduction of sysevent_evc_subscribe and sysevent_subattr_* int sysevent_evc_xsubscribe(evchan_t *, const char *, const char *, int (*)(sysevent_t *, void *), void *, uint32_t, sysevent_subattr_t *); This new interface is described in the accompanying manpage (not for delivery, but previous GPEC cases have included manpages). This interface is a sibling to sysevent_evc_subscribe, but uses door_xcreate(3C) to create a private door for delivery of matching events. The additional argument of a sysevent_subattr_t permits substantial control over the door server threads that are used in these event delivery invocations. This interface is defined for userland only (the private doors it uses are meaningless in the kernel). typedef struct sysevent_subattr sysevent_subattr_t; sysevent_subattr_t *sysevent_subattr_alloc(void); void sysevent_subattr_free(sysevent_subattr_t *); int sysevent_subattr_thrattr(sysevent_subattr_t *, pthread_attr_t *); void sysevent_subattr_sigmask(sysevent_subattr_t *, sigset_t *); 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 *); These interfaces are described in the sysevent_evc_xsubscribe manpage. They provide control over the threads that are use to deliver event callbacks. 4.5. Interfaces: The GPEC (general-purpose event channel) interface was introduced in PSARC/2002/321 as an Evolving interface. Before Solaris 10 FCS this was revised to Consolidation Private in PSARC/2004/398. Some new publication flags were introduced in PSARC/2004/411, and the mechanism virtualized for zones in PSARC/2004/472. While GPEC remains Consolidation Private, it is apparent that it is in use outside of ON (I believe Sun cluster uses GPEC) so the interfaces are evolved compatibly, and changes continue to be ARCed despite being private. New Exported Interface Stability ------------------------------- ------------ EVCH_HOLD_PEND_INDEF Consolidation Private sysevent_evc_xsubscribe Consolidation Private sysevent_subattr_alloc Consolidation Private sysevent_subattr_free Consolidation Private sysevent_subattr_thrattr Consolidation Private sysevent_subattr_thrcreate Consolidation Private sysevent_subattr_thrsetup Consolidation Private Modifed Exported Interface Stability ------------------------------- ------------ sysevent_evc_unsubscribe Consolidation Private sysevent_evc_unbind Consolidation Private Imported Interface Stability ------------------------------- ------------ door_xcreate Committed (PSARC/2009/554) 4.6. Doc Impact: None - the GPEC interface is Consolidation Private (as per revision in PSARC/2004/398). A manpage for the new interfaces is included simply to match those offered in PSARC/2002/321. 6.4. Product Approval Committee requested information: 6.4.1. Consolidation or Component Name: ON 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open