Event contexts

The scheduling attributes contained in *attr are used when creating this thread; if attr is NULL then the default thread attributes are used. Since pevent_ctx_create() makes a copy of these attributes, attr may be discarded when pevent_ctx_create() returns.

mtype is the typed_mem(3) memory type used when allocating memory for the event context.

pevent_ctx_destroy() destroys an event context. Any events still registered are automatically unregistered. Upon return, *ctxp is set to NULL. If *ctxp is already NULL when pevent_ctx_destroy() is invoked, nothing happens.

It is safe to call pevent_ctx_destroy() from within an event handler function.

pevent_ctx_count() returns the number of events currently registered with ctx.

Events

handler must point to a function having this type:

typedef void pevent_handler_t(void *arg);

When the event occurs, *peventp is set to NULL and then handler(arg) is invoked. Therefore, *peventp is not equal to NULL if and only if the event is still pending. For this to work, *peventp must remain valid and unmodified while the event is pending, and the user code must initialize peventp to NULL before the first call to pevent_register().

The type and subsequent argument(s) define the event itself; type may have be one of the following values:

The flags parameter may contain any of the following values OR'd together:

PEVENT_RECURRING causes the event to be automatically re-registered just before each invocation of handler(). In particular, this means that *peventp will not be NULL when handler() is invoked.

PEVENT_OWN_THREAD causes a new thread to be spawned for each invocation of handler(); this thread may block, exit, or be canceled, and is by default not joinable. If this flag is not set, handler() will execute in the event context's main thread, in which case handler() must not block or exit and the thread must not be canceled.

pevent_unregister() unregisters the event referenced by *peventp. Upon return, *peventp is set to NULL. If *peventp is already NULL when pevent_unregister() is invoked, nothing happens.

pevent_trigger() manually triggers an event, causing its handler to be invoked. Although intended for use with PEVENT_USER events, it will work with any event. The event may be NULL, in which case nothing happens.

pevent_get_info() returns the type and parameters associated with event by filling in the struct pevent_info structure pointed to by info:

struct pevent_info {
    enum pevent_type    type;    /* event type */
    union {
        int              fd;       /* file descriptor (READ, WRITE) */
        int              millis;   /* delay in milliseconds (TIME) */
        struct mesg_port *port;    /* message port (MESG_PORT) */
    };                  u;
};

Synchronization

If a non- NULL mutex is provided to pevent_register(), then pevent will acquire *mutex just before setting *pevent to NULL and invoking handler(), and *mutex will be automatically released when handler() returns (or, in the case of PEVENT_OWN_THREAD, the handler thread exits by any means). If the user code acquires this mutex before any calls to pevent_register() or pevent_unregister(), or before accessing *eventp, then *eventp will always reflect the 'registered' state of the event and handler() is guaranteed to never be invoked after pevent_unregister() returns.