postwait_post, postwait_postn - Post user events to a key to notify one or more waiters.
int postwait_post(postwkey_t key, int uevents, uintptr_t udata);
int postwait_postn( postwkey_t klist, postwkey_uevdata_t userd, int errors, uint_t nent);
int postwait_post_deferred( postwkey_t key, int flags, int uevents, uintptr_t udata);
The postwait_post(), postwait_postn(), and postwait_post_deferred() functions allow threads to post events as part of a post-wait mechanism. Threads can wait and retrieve these events via event ports.
Post events consist of an user defined integer type event and an unsigned long item of opaque user data. Both fields are available to the receiving threads.
The post-wait mechanism can be used between threads in the same or different processes. A key is used as the rendezvous point for posting and waiting; these 64 bit keys are generated by postwait_genkey (3C) call and shared with other processes using any desired form of IPC. No limitations are placed on which processes may use which keys.
The postwait_post() function causes an event of type PORT_SOURCE_POSTWAIT and the associated user values to be delivered to any event ports that are associated with the specified key. For more information, see port_associate(3C).
The postwait_postn() function posts multiple post events to multiple keys with one system call. Passing NULL for the errors argument could cause this function to post asynchronously with the help of background worker threads. The list of keys to be posted to are passed in the klist array argument. The corresponding user events and user data are passed in the array of struct postwkey_uevdata_t. The number of elements of this array is specified in nent argument. Passing NULL for userd causes 0 to be used as the value of uevents and udata.
The postwkey_uevdata_t structure contains the following members:
int pwev_uevents; uintptr_t pwev_udata;
The postwait_post_deferred() function is for registering a deferred post. With PWPOST_ATEXIT specified in flags, the deferred post is delivered when the thread that registered the post exits the containing process exits or is killed. Calling postwait_post_deferred() with PWPOST_CANCEL flag will cancel any outstanding deferred post registered for the key by this thread. There can be only one deferred post registered by a thread per key.
If PWPOST_VALIDATE_KEY is or'd with PWPOST_ATEXIT , it checks if the key specified is associated with an event port or not. If not, the deferred post registration for that key will fail.
To receive post events, the key needs to be associated with an event port. Threads collect the post events from the event port. Delivery of the post event and user values is determined by the associating type of key. Two types of association are permitted: counting and queuing. For more information, see port_associate(3C) .
For a counting type association, multiple posts that occur before the event is retrieved will be combined resulting in just one event delivery to the event port. A count indicating how many times the key was posted since the last time that an event for that key was collected is returned along with the event. Both the user event and the user data submitted with the post will be ignored for this type of association.
For a queuing type association, one event for each post will be queued on the event port. The user event and user data passed are delivered with the posted event. The number of events that can get queued on an event port is subject to the process.max-port-events resource limit. For more information, see rctladm(1M).
If a key is associated with more then one event port, a post to that key will result in delivery of the same event to each of those ports.
Upon successful completion, postwait_post() will return 0. Otherwise, it will return -1 and sets errno to indicate the error.
In the synchronous mode, the postwait_postn() function returns the number of successfully submitted events. A non-negative return value less than the nent argument indicates that at least one error has occurred. In this case, each element of the errors array is filled in. An element of the errors array is set to 0 if the post event was successfully sent to the corresponding key in the klist array, or is set to indicate the error if not successful.
In the asynchronous mode, postwait_postn() function returns the number of successfully handed-off events. If an error occurs with the postwait_postn() call, it returns -1 and sets errno to indicate the error.
The postwait_post_deferred() function returns 0, if the deferred post is registered or cancelled successfully. Otherwise it returns -1 and the errno is set to indicate the error.
The postwait_post() and synchronous mode postwait_postn() functions will fail if:
The maximum number of events per port is exceeded. The maximum allowable number of events per port is the minimum value of the process.max-port-events resource control at the time port_create(3C) was called to create the event port to which the key is associated.
The event cannot be delivered as the specified key currently is not associated with any event ports.
The postwait_post() and postwait_postn() functions will fail if:
There is not enough memory available to satisfy the request.
The postwait_postn() function will fail if:
The klist or userd or errors pointer is invalid.
The postwait_post_deferred() function will fail if:
If there is already a deferred post registered for the specified key.
If the PWPOST_CANCEL flag is passed and there is no deferred post registered for the specified key or the value passed in flags argument are invalid.
If the thread has already registered maximum number of allowed deferred posts defined by process.max-deferred-posts resource control.
If PWPOST_VALIDATE_KEY flag was or'd with PWPOST_ATEXIT, and the key specified is currently not associated with any port. Note that after the key has been validated here, it is possible that the process that has associated the key can exit or get killed. As a result, the key may no longer be associate with any event port. However, a different process can subsequently associate the same key with an event port.
See attributes(5) for descriptions of the following attributes: