The SYSTEM_EVENTS feature enables a user-level application to be notified of the occurrence of events in the system and/or drivers. The following events are posted by the system and received by the application:
Gauges crossing their threshold
Creation or destruction of processes and, optionally, actors
File system mounts and unmounts
Detection of error in a driver
Detection of error in the operating system
System events are carried by messages that are placed in different queues, depending upon the kind of events. In the ChorusOS operating system, the system events feature relies on the MIPC microkernel feature. The maximum number of system events that can be queued by the system is fixed by a tunable, set when you build the system.
The system events feature is also available to user-level applications to exchange events and is not restricted to system-level communication.
In the context of system events, the following terms are defined:
An event is something that happens inside one entity corresponding to a change in the abstract state of that subsystem or application. Events are not generally observable from outside the entity, and cannot correspond to a change in the actual state of the entity. The entity in which the event occurs can notify certain user applications of the occurrence.
An event publisher is the entity that notifies other entities of the occurrences of a particular set of events. Notification of occurrences of events can be made directly to interested entities or through an intermediary dispatcher. The events can be generic to a particular technology or specific to the event publisher.
An event subscriber is an entity that is interested in the occurrence of certain events. It can subscribe its interest directly with the event publisher or with some intermediary entity to receive event notifications.
An event buffer is passed from an event publisher to an event consumer to indicate that an event has occurred. The buffer includes information to describe the occurrence of an event in a particular publisher. The event buffer can be passed directly from the publisher to the consumer, or through an intermediary dispatcher.
At a minimum, an event is described by its event type, event identifier and publisher ID. These three fields combine to form the event buffer header. The goal is to provide a simple and flexible way to describe the occurrence of an event. If additional information is required to describe the event further, a publisher can provide a list of self-defined attributes. Event attributes contain an event attribute name/value pair that combine to define that attribute. Event attributes are used in event objects to provide self-defining data as part of the event buffer. The name of the event attribute is a character string. The event attribute value is a self-defining data structure that contains a data-type specifier and the appropriate union member to hold the value of the data specified.
Applications are provided a libnvpair to handle the attribute list and to provide a set of interfaces for manipulating name-value pairs. The operations supported by the library include adding and deleting name-value pairs, looking up values, and packing the list into contiguous memory to pass it to another address space. The packed and unpacked data formats are freshened internally. New data types and encoding methods can be added with backward compatibility.
To enable the code of this library to be linked to the Solaris kernel or to the ChorusOS operating system, the standard errno variable is not used to notify the caller that an error occurred. Error values are returned by the library functions directly.
The system events API is summarized in the following table:
Function |
Description |
---|---|
sysevent_get_class_name() |
Get the class name of the event |
sysevent_get_subclass_name() |
Get the subclass name |
sysevent_get_size() |
Get the event buffer size |
sysevent_get_seq() |
Get the event buffer size |
sysevent_get_time() |
Get the time stamp |
sysevent_free() |
Free memory for system event handle |
sysevent_post_event() |
Post a system event from userland |
sysevent_get_event() |
Wait for a system event |
sysevent_get_attr_list() |
Get the attribute list pointer |
sysevent_get_vendor_name() |
Get the publisher vendor name |
sysevent_get_pub_name() |
Get the publisher name |
sysevent_get_pid() |
Get the publisher PID |
sysevent_lookup_attr() |
Search the attribute list |
sysevent_attr_next() |
Returns the next attribute associated with event |
sysevent_dup() |
Duplicate a system event |