dispatch_context_alloc()
Return a dispatch context
Synopsis:
#include <sys/iofunc.h>
#include <sys/dispatch.h>
dispatch_context_t* dispatch_context_alloc( dispatch_t * dpp );
Arguments:
- dpp
- A dispatch handle created by a successful call to dispatch_create().
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The dispatch_context_alloc() function returns a dispatch context pointer. The function is passed in the handle dpp from dispatch_create(). The dispatch context is used by dispatch to do its work. It's passed as an argument to dispatch_block() and dispatch_handler().
- The dispatch_context_alloc() function fails if you haven't attached any events to dispatch yet (i.e., you didn't call message_attach(), pulse_attach(), resmgr_attach(), or select_attach()).
- Once you've called dispatch_context_alloc(), don't call message_attach() or resmgr_attach() specifying a larger maximum message size or a larger number of message parts for the same dispatch handle. These functions indicate an error of EINVAL if this happens.
- The returned dispatch_context_t* value is a pointer to a union of various callback-specific structures, in particular: a resmgr_context_t, a message_context_t (which is identical to a resmgr_context_t), and a select_context_t.
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.
Returns:
A pointer to a dispatch context, or NULL if an error occurs (errno is set).
Errors:
- EINVAL
- No events were attached.
- ENOMEM
- Insufficient memory to allocate context.
Examples:
#include <sys/dispatch.h>
#include <stdio.h>
#include <stdlib.h>
int main( int argc, char **argv ) {
dispatch_t *dpp;
dispatch_context_t *ctp;
if( ( dpp = dispatch_create() ) == NULL ) {
fprintf( stderr, "%s: Unable to allocate \
dispatch handle.\n",argv[0] );
return EXIT_FAILURE;
}
...
ctp = dispatch_context_alloc( dpp );
...
return EXIT_SUCCESS;
}
For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | No |
| Thread | Yes |