pulse_attach()

Attach a pulse code

Synopsis:

#include <sys/dispatch.h>

int pulse_attach( dispatch_t * dpp,
                  int flags,
                  int code,
                  int (* func)
                      ( message_context_t * ctp,
                        int code,
                        unsigned flags,
                        void * handle ),
                  void * handle );

The pulse_attach() function attaches a pulse code to a user-supplied function func. The same function func can also be used in message_attach(). When the resource manager receives a pulse that matches code, it calls func. This user-supplied function is responsible for doing any specific work needed to handle the pulse pointed to by ctp->msg.pulse. The handle passed to the function is the handle initially passed to pulse_attach(). The handle may be a device entry you want associated with the pulse code.

The pulse_attach() function is typically used to associate pulses generated by interrupt handlers or timers with a routine in the main of your resource manager. By examining ctp->rcvid, the func function can determine whether a pulse or message was received.

Flags

Currently, the following flags is defined in <sys/dispatch.h>:

MSG_FLAG_ALLOC_PULSE: Dispatch allocates and attaches a pulse code that's different than any other code that was either given to pulse_attach() through the code parameter, or allocated by pulse_attach(). The allocated code is in the range _PULSE_CODE_MINAVAIL and _PULSE_CODE_MAXAVAIL.

Returns:

If MSG_FLAG_ALLOC_PULSE is specified, the function returns the allocated pulse code; otherwise, it returns the code that's passed in. On failure, -1 is returned (errno is set).

Errors:

EAGAIN: Couldn't allocate a pulse code.
EINVAL: Pulse code is out of range or it's already registered.
ENOMEM: Insufficient memory to allocate internal data structures.

Examples:

#include <sys/dispatch.h>
#include <time.h>
#include <stdio.h>    
#include <stdlib.h>
        
int my_func( ... ) {

   ...

}
        
int main( int argc, char **argv ) {
   dispatch_t    *dpp;
   int           flag = 0, code, mycode;
    
   if ( ( dpp = dispatch_create() ) == NULL ) {
      fprintf( stderr, "%s: Unable to allocate \
               dispatch handle.\n",argv[0] );
      return EXIT_FAILURE;
   }

   ...

   mycode = ...;

   if ( (code = pulse_attach( dpp, flag, mycode,
                &my_func, NULL)) == -1 ) {
      fprintf ( stderr, "Failed to attach code %d.\n", mycode );
      return 1;
   }
   /* else successfully attached a pulse code */
            
   ...
}

For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes