int linx_receive(LINX *linx, union LINX_SIGNAL **sig, const LINX_SIGSELECT
*sig_sel);
int linx_receive_w_tmo(LINX *linx, union LINX_SIGNAL **sig, const LINX_SIGSELECT
*sig_sel, LINX_OSTIME tmo);
int linx_receive_from(LINX *linx, union LINX_SIGNAL **sig, const LINX_SIGSELECT
*sig_sel, LINX_OSTIME tmo, LINX_SPID from);
int linx_receive_w_buf(LINX *linx, union LINX_SIGNAL **sig, const LINX_SIGSELECT
*sig_sel);
linx_receive() will wait indefinitely for a signal buffer that matches
the sig_sel filter. sig_sel filters are described in linx(7)
.
linx_receive_w_tmo() waits until the provided timeout, tmo, has elapsed
or for a signal buffer that matches the sig_sel filter. At timeout zero
is returned and sig is set to LINX_NIL instead of a pointer to a signal
buffer.
linx_receive_from() works in the same way as linx_receive_w_tmo() except
that it will only accept signal buffers sent from the LINX endpoint, indicated
by the spid from.
linx_receive_w_buf() is the only call where a preallocated signal buffer
is mandatory. The received signal buffer contents will be stored in sig
and if it does not fit, sig will be automatically resized. Apart from this,
linx_receive_w_buf() works in the same way as linx_receive(). Note that
the provided signal buffer, sig, must be allocated from the same LINX
endpoint, on which the signal is received. At an error, LINX will have freed
the preallocated buffer and set sig to LINX_NIL. It may be efficent to
use a preallocated buffer, if a very large signal buffer is expected, avoiding
multiple resizing operations which otherwise might be needed internally
in LINX while receiving the buffer.
linx is the handle to the LINX endpoint, via which the signal buffers
are received.
sig is the received signal buffer. A preallocated signal buffer may only
be used with linx_receive_w_buf(). Do _not_ use a preallocated signal buffer
in the other variants of linx_receive(), as this will be lost.
sig_sel is a select filter, defining which type of buffers to receive.
It is a list of signal numbers (and a leading value, telling the number
of signal numbers in the list). Read more about select filters in linx(7)
.
tmo is the maximum number of milliseconds to wait. The value 0 means wait
indefinitely, or until receiving a signal buffer.
from is the spid of the other LINX endpoint to receive from. Before linx_receive_from() is used, it is important to attach to the other LINX endpoint with linx_attach(3) and also to include the attach signal number in the sig_sel filter. If this is not done and the other LINX endpoint (with spid from ) is closed, this call will block the entire specified timeout.
If linx is not a valid LINX endpoint, i.e. created with linx_open(3) then abort(3) is called.
If unsuccessful, -1 is returned and errno is set.
ENOMEM if there is not enough memory.
EBADF, EFAULT, ENOTCONN, ENOTSOCK if the underlying linx structure contains
a invalid socket descriptor.
EINTR the call was interrupted by a signal.
In case the application needs to wait on multiple sockets of different kinds, the internal socket descriptor in a LINX endpoint can be fetched with linx_get_descriptor(3) and used in a select(2) or poll(2) call to wake up if anything arrives at the LINX endpoint.
Signal file (exemple.sig):
#include <linx.h>
#define SIG_X 0x1
#define SIG_Y 0x2
#define SIG_Z 0x3
#define SIG_W 0x4
/* select filter is { number-of-signals, signal, signal, ... } */
static const LINX_SIGSELECT sigsel_any[] = { 0 };
static const LINX_SIGSELECT sigsel_sig_x_z[] = { 2, SIG_X, SIG_Z };
static const LINX_SIGSELECT sigsel_sig_w[] = { 1, SIG_W };
Server:
#include <linx.h>
#include "example.sig"
int
main (int argc, char *argv[])
{
LINX *linx;
LINX_SPID client;
union LINX_SIGNAL *sig;
/* Open a linx endpoint with huntname "server" */
linx = linx_open("server", NULL, 0);
/* Hunt for client */
linx_hunt(linx, "client", NULL);
/* Receive hunt signal */
linx_receive(linx, &sig, LINX_OS_HUNT_SIG);
/* Retrive client's spid */
client = linx_sender(linx, &sig);
/* Free the hunt signal */
linx_free_buf(linx, &sig);
/* Send four signals, they will be stored in the receive
* queue on the client in same order as sent but the
* client chooses in which order to retrive them from
* the queue.
*/
/* Send signal with signal number SIG_X */
sig = linx_alloc(linx, sizeof(LINX_SIGSELECT), SIG_X);
linx_send(linx, &sig, client);
/* Send signal with signal number SIG_Y */
sig = linx_alloc(linx, sizeof(LINX_SIGSELECT), SIG_Y);
linx_send(linx, &sig, client);
/* Send signal with signal number SIG_Z */
sig = linx_alloc(linx, sizeof(LINX_SIGSELECT), SIG_Z);
linx_send(linx, &sig, client);
/* Send signal with signal number SIG_W */
sig = linx_alloc(linx, sizeof(LINX_SIGSELECT), SIG_W);
linx_send(linx, &sig, client);
linx_free_buf(linx, &sig);
/* Close the linx endpoint */
linx_close (linx);
}
Client:
#include <linx.h>
#include "example.sig"
int
main (int argc, char *argv[])
{
LINX *linx;
LINX_SPID client;
/* Open a linx endpoint with huntname "client" */
linx = linx_open("client", NULL, 0);
/* Check for signal SIG_W first */
linx_receive(linx, &sig, sigsel_sig_w);
/* Do work, sig->sig_no is SIG_W */
/* Free signal when done */
linx_free_buf(linx, &sig);
/* Receive the the first signal waiting in the receive queue */
linx_receive(linx, &sig, sigsel_any);
/* Do work, sig->sig_no is SIG_X */
linx_free_buf(linx, &sig);
/* Receive either SIG_X or SIG_Z from the receive queue. */
linx_receive(linx, &sig, sigsel_sig_x_z);
/* Do work, sig->sig_no is SIG_Z (SIG_X has been consumed) */
linx_free_buf(linx, &sig);
/* Receive the the first signal waiting in the receive queue */
linx_receive(linx, &sig, sigsel_any);
/* Do work, sig->sig_no is SIG_Y */
linx_free_buf(linx, &sig);
linx_close (linx);
}
Copyright (c) 2006-2007, Enea Software AB All rights
reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer. Redistributions in
binary form must reproduce the above copyright notice, this list of conditions
and the following disclaimer in the documentation and/or other materials
provided with the distribution. Neither the name of Enea Software AB nor
the names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.