Block while waiting for an event
#include <sys/iofunc.h> #include <sys/dispatch.h> dispatch_context_t * dispatch_block ( dispatch_context_t * ctp );
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The dispatch_block() function blocks by calling MsgReceive() while waiting for an event that's registered using one of the attach functions, message_attach(), pulse_attach(), resmgr_attach(), or select_attach(). This function is part of the dispatch layer of a resource manager. For more information, see "Layers in a resource manager" in the Bones of a Resource Manager chapter of Writing a Resource Manager.
A dispatch context that's passed in by dispatch_context_alloc(). or NULL if an error occurs (errno is set).
Errors can occur when the blocking kernel call returns with an error, for example, due to the delivery of a signal.
If a non-NULL context pointer is returned, it could be different from the one passed in, as it's possible for the ctp to be reallocated to a larger size. In this case, the old ctp is no longer valid. However, if NULL is returned (for example, because a signal interrupted MsgReceive()), the old context pointer is still valid. Typically, a resource manager would target signals to a thread dedicated to handling signals. However, if a signal can be targeted to the thread doing dispatch_block(), you could use the following code in this situation:
dispatch_context_t *ctp, *new_ctp; ctp = dispatch_context_alloc( … ); while (1) { new_ctp = dispatch_block( ctp ); if ( new_ctp ) { ctp = new_ctp } else { /* handle the error condition */ … } }
See also the error constants returned by MsgReceive() and SignalWaitinfo().
#include <sys/dispatch.h> int main( int argc, char **argv ) { dispatch_context_t *ctp; … for(;;) { if( ctp = dispatch_block( ctp ) ) { dispatch_handler( ctp ); } } }
For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().
Safety: | |
---|---|
Cancellation point | Yes |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |