pulse_attach()

Arguments:

dpp

The dispatch handle, as returned by a successful call to dispatch_create().

flags

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

• MSG_FLAG_ALLOC_PULSE — allocate and attach a pulse code that's different than any other code that was either given to pulse_attach() through the code argument, or allocated by pulse_attach(). The allocated code is in the range _PULSE_CODE_MINAVAIL through _PULSE_CODE_MAXAVAIL.

code

The pulse code that you want to attach the function to. You can use one of the predefined _PULSE_CODE_* codes in <sys/neutrino.h>, or you can use your own value in the range from _PULSE_CODE_MINAVAIL to _PULSE_CODE_MAXAVAIL. This argument is ignored if you specify MSG_FLAG_ALLOC_PULSE in the flags.

func

The function that you want to call when a message in the given range is received; see below, as well as “Handler function” in the documentation for message_attach().

handle

An arbitrary handle that you want to associate with data for the defined message range. This handle is passed to func.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pulse_attach() function attaches a pulse code to a user-supplied function, func. You can use the same function func with message_attach(). By examining ctp->rcvid, the func function can determine whether a pulse or message was received.

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 identified 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. Your function should return 0; other return values are reserved.

You typically use pulse_attach() to associate pulses generated by interrupt handlers or timers with a routine in the main program of your resource manager.

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.

EBUSY

You're attaching a handler for _PULSE_CODE_COIDDEATH, and the dispatch handle can't accept such a handler. A dispatch handle can accept such a handler if any of the following is true:

• The dpp was the first dispatch handle created in the process with dispatch_create().
• The dpp was the first dispatch handle created in the process with dispatch_create() after the destruction of a dispatch handle that could accept such a handler.
• The dpp was a dispatch handle created with dispatch_create_channel() with the DISPATCH_CHANNEL_COIDDEATH flag set.

EINVAL

The pulse code is out of range, or it's already registered.

ENOMEM

Insufficient memory to allocate internal data structures.

EPERM

The calling process doesn't have the required permission; see procmgr_ability().

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 Neutrino