Signals

Functions

sig_t * sig_create (signo_t signo, size_t size)
void sig_destroy (sig_t *sig)
task_t * sig_get_sender (sig_t *sig)
void sig_receive (signo_t *filter, sig_t **sig)
int sig_receive_tmo (signo_t *filter, sig_t **sig, tick_t time)
void sig_send (task_t *task, sig_t *sig)

Function Documentation

sig_t* sig_create ( signo_t  signo,
size_t  size 
)

Allocates and initialises a signal. The number of bytes specified by size will be allocated as data space for the signal.

Parameters:
signo A number identifying the signal
size The number of bytes allocated for the signal

The signal number 0 is reserved for terminating filter lists and should not be used otherwise.

Returns:
The signal handle to be used in all subsequent operations on the signal.
void sig_destroy ( sig_t *  sig  ) 

Frees the resources allocated by the signal.

Parameters:
sig Signal handle
task_t* sig_get_sender ( sig_t *  sig  ) 

Returns the id of the task that sent signal sig.

This function can be used to return the result of a requested operation, for instance in a client/server application.

 void handleJob (struct sig_job * sig)
 {
    // Do job
    ....

    // Send response
    sig->jobOk = 1; // Success!
    sig_send (sig_get_sender (sig), sig);
 }

Note that in this case the signal is reused. It is still the receiving tasks responsibility to free the signal. In this case it will therefore be the task that originally sent the signal (provided the signal isn't reused again).

Parameters:
sig Pointer to signal
Returns:
The task id of the sender
void sig_receive ( signo_t *  filter,
sig_t **  sig 
)

Receives a signal. If no signals are available after filtering, the calling task will be put in the WAITING state. If a signal is available after filtering, the function will return immediately.

The filter parameter is used to accept only wanted signals. If filter is NULL, then no filter is applied and all signals will be considered.

If filter is not NULL then it should point to a zero-terminated array of signo_t values. Each value in the array specifies a signal number that the task is interested in. Signal numbers not included in the array will be filtered out.

The signal number 0 is reserved for terminating filter lists and should not be used otherwise.

A pointer to the signal is stored in sig.

 struct sig_foo
 {
    signo_t signo;
    char str[8];
 };

 struct sig_bar
 {
    signo_t signo;
    uint32_t retval;
 };

 #define SIG_FOO 1
 #define SIG_BAR 2

 void myTaskEntry (void * arg)
 {
    for (;;)
    {
       static signo_t filter[] = { SIG_BAR, SIG_FOO, 0 };
       sig_t * incoming;

       // Wait for signals SIG_FOO or SIG_BAR
       sig_receive (filter, &incoming);

       // Do work according to signal
       switch (incoming->signo)
       {
       case SIG_FOO:
       {
          struct sig_foo * sig = (struct sig_foo *)incoming;
          if (strcmp (sig->str, "somedata") == 0)
          {
             ...
          }
          break;
       }  
       case SIG_BAR:
       {
          struct sig_bar * sig = (struct sig_bar *)incoming;
          handleBar (sig);
          break;
       }
       ...
       }

       // Free signal
       sig_destroy (incoming);
    }
 }

Signals have an ownership associated with them. The signal is owned by the task that receives it. The receiving task is therefore responsible for freeing the resources associated with the signal.

Parameters:
filter List of signals to accept
sig Pointer to signal
int sig_receive_tmo ( signo_t *  filter,
sig_t **  sig,
tick_t  time 
)

Analogous to sig_receive(), but a maximum time to wait can be specified. If no signal is available after filtering, the calling task will wait until a signal becomes available, or the number of ticks given by time expires.

Parameters:
filter List of signals to accept
sig Pointer to signal
time Number of ticks to wait
Returns:
0 if a signal was received successfully, 1 if the service timed out.
void sig_send ( task_t *  task,
sig_t *  sig 
)

Sends a signal. The signal sig is sent to task.

The signal must have been created using sig_create().

 void sendFoo (void)
 {
    sig_t * sig;

    sig = sig_create (SIG_FOO, sizeof (struct sig_foo));
    strcpy (sig->data, "the data", 8);
    sig_send (task_find ("myTask"), sig);
 }

Note that ownership of the signal is lost after it is sent. The task should make no further attempt to reference the signal after sending it.

Parameters:
task Task that will receive signal
sig Pointer to signal
rt-kernel