svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
postwait_post(3c)
Standard C Library Functions postwait_post(3C)
NAME
postwait_post, postwait_postn, postwait_post_deferred - Post user
events to a key to notify one or more waiters.
SYNOPSIS
#include <port.h>
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);
DESCRIPTION
The postwait_post(), postwait_postn(), and postwait_post_deferred()
functions allow threads to post events as part of a post-wait mecha‐
nism. 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 dif‐
ferent 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 limi‐
tations are placed on which processes may use which keys.
The postwait_post() function causes an event of type PORT_SOURCE_POST‐
WAIT 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 ele‐
ments 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 regis‐
tered 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 deliv‐
ery 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 the rctladm(8) man page.
The count and the user values are delivered in the port_event_t struc‐
ture. The events from an event port are collected using port_get(3C) or
port_getn(3C) calls.
If a key is associated with more than one event port, a post to that
key will result in delivery of the same event to each of those ports.
RETURN VALUES
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 num‐
ber 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 ele‐
ment of the errors[] array is set to 0 if the post event was success‐
fully 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 post‐
wait_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.
ERRORS
The postwait_post() and synchronous mode
postwait_postn() functions will fail if:
EAGAIN The maximum number of events per port is exceeded. The maxi‐
mum 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.
EBADF 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:
ENOMEM There is not enough memory available to satisfy the request.
The postwait_postn() function will fail if:
EFAULT The klist[] or userd[] or errors[] pointer is invalid.
The postwait_post_deferred() function will fail if:
EBUSY If there is already a deferred post registered for the speci‐
fied key.
EINVAL 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.
EAGAIN If the thread has already registered maximum number of
allowed deferred posts defined by process.max-deferred-posts
resource control.
EBADF 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 possi‐
ble 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 subse‐
quently associate the same key with an event port.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe, Async-Sig‐
nal-Safe
SEE ALSO
port_create(3C), port_sendn(3C), postwait_genkey(3C), resource-con‐
trols(7)
Oracle Solaris 11.4 11 May 2021 postwait_post(3C)