dispatch_block()
Block while waiting for an event
Synopsis:
#include <sys/iofunc.h>
#include <sys/dispatch.h>
dispatch_context_t * dispatch_block
( dispatch_context_t * ctp );
Since:
BlackBerry 10.0.0
Arguments:
- ctp
- A pointer to a dispatch_context_t structure that defines the dispatch context.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The dispatch_block() function blocks while waiting for an event (e.g. message or signal) that's registered using one of the attach functions, message_attach(), pulse_attach(), resmgr_attach(), or select_attach(). (The sigwait_attach() function isn't currently implemented.)
| If the type of blocking is: | dispatch_block() does a: |
|---|---|
| message (resmgr, message, select) | MsgReceive() |
| signal | SignalWaitinfo() |
Returns:
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.
In the case of a timeout, a valid ctp is returned, but either the ctp->message_context.rcvid or ctp->sigwait_context.signo is set to -1.
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 the 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 */
…
}
}
Errors:
- EFAULT
- A fault occurred when the kernel tried to access the buffers.
- EINTR
- The call was interrupted by a signal.
- EINVAL
- Invalid arguments passed to dispatch_block().
- ENOMEM
- Insufficient memory to allocate internal data structures.
See also the error constants returned in MsgReceive() and SignalWaitinfo().
Examples:
#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().
Classification:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Interrupt handler | No |
| Signal handler | Yes |
| Thread | Yes |
Last modified: 2014-06-24