NAME

mr_receive – receive a message or signal

SYNOPSIS

#include <mrendez.h>

pthread_t mr_receive( void *rqst,

BitMask portmask, BitMask sigmask, int *outport,

struct timespec *timeout);

DESCRIPTION

The mr_receive() primitive is used to receive messages and/or signals from threads. ISRs can also send signals. If both signals and messages are available at the time of the call, the highest priority signal is accepted; otherwise, the first suitable signal or message is accepted.

A message can be sent to the calling thread via the mr_send() primitive. The message is received into the area pointed to by request. Note that the sending thread then blocks until a reply message is received. This reply message is sent by the receiver using mr_reply().

The portmask implements a selective accept mechanism using the ports defined by mr_init() and the signals availble to the thread. This argument is a 32 bit port mask indicating which ports the thread is willing to accept a message through. The ports are numbered 0 through 31. To accept from port n, bit (1 << n ) must be set in the portmask.

The mr_init() function must be called before mr_receive can be called. The ports argument to mr_init() limits how many ports can actually be received through. It is not an error to set a port in the portmask higher than ports, but no messages will come through the port.

A signal may be sent to the calling thread by threads or ISRs via the mr_sigpost() primitive.

The sigmask implements part of the selective accept mechanism. This argument works just like the portmask described above. All threads can accept all 32 signals, there is no limit as in ports.

The actual port or signal received is set in outport. The value returned in outport is the port or signal number, not it’s mask. The argument outport may be NULL if this value is not needed.

The timeout argument specifies the time that the caller is willing to wait before the system should indicate that the no signal or message was received. The define FOREVER can be defined if the call should never timeout.

NOTES

Signals of each value are not queued for the thread by the system; therefore, a thread cannot have more than one outstanding signal of each value at any time. The lower a signal’s value, the higher its priority; the system does not interpret the value of signals in any other way.

Signals are not to be confused with POSIX signals. They are used to transmit binary events from ISRs to threads and other OS events to threads without blocking the sender. They only occur once – multiple occurances of signals register as a single binary event.

The contents of the rqst are undefined when a signal is received.

There is no guarantee as to which order messages are received from multiple ports, if more than one port contains a message, other than that a fair scheduling algorithm is implemented. Messages are queued FIFO within each particular port.

The first 16 bits of the rqst argument are taken to be the maximum size, in bytes, of the message which may be written into rqst. The lesser of this size and the size obtained from the sender’s rqst argument represents the number of bytes actually copied by the system. Note that since the size bytes are the first two bytes transferred, it is possible to determine if the rqst was truncated.

RETURN VALUES

If a signal is received, mr_receive() returns INTERRUPT_ID. If a message is received, mr_receive returns the sending threads’s id. A zero is returned if the call failed.

The number of the signal received, or the number of the port through which the message was received, is returned in outport.

The sender’s request, if any, is returned in the area pointed to by rqst.

ERRORS

ENOENT

The receiveing thread has not called mr_init().

ETIMEDOUT

The calling threads’s receive request could not be fulfilled within the time period specified by timeout.

SEE ALSO

mr_init(), mr_send(), mr_reply()