SolarCapture C Bindings User Guide  SF-115721-CD
Issue 3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
mailbox.h File Reference

sc_mailbox: A means to pass packets from one thread to another. More...

Functions

int sc_mailbox_alloc (struct sc_mailbox **mb_out, const struct sc_attr *attr, struct sc_thread *thread)
 Allocate a mailbox. More...
 
int sc_mailbox_connect (struct sc_mailbox *mb1, struct sc_mailbox *mb2)
 Connect a pair of mailboxes. More...
 
int sc_mailbox_set_recv (struct sc_mailbox *mailbox, struct sc_node *node, const char *name_opt)
 Connect a mailbox to a node. More...
 
struct sc_nodesc_mailbox_get_send_node (struct sc_mailbox *mailbox)
 Return a mailbox's "send node". More...
 
int sc_mailbox_poll (struct sc_mailbox *mailbox, struct sc_packet_list *list)
 Poll a mailbox. More...
 
void sc_mailbox_send (struct sc_mailbox *mailbox, struct sc_packet *packet)
 Send a packet through a mailbox to another thread. More...
 
void sc_mailbox_send_list (struct sc_mailbox *mailbox, struct sc_packet_list *list)
 Send a list of packets through a mailbox to another thread. More...
 

Detailed Description

sc_mailbox: A means to pass packets from one thread to another.

Function Documentation

int sc_mailbox_alloc ( struct sc_mailbox **  mb_out,
const struct sc_attr attr,
struct sc_thread *  thread 
)

Allocate a mailbox.

Parameters
mb_outThe allocated mailbox is returned here.
attrAttributes (see sc_attr).
threadThe thread the mailbox will be in.
Returns
0 on success, or a negative error code.

Mailboxes are used to pass packets between threads. To communicate you need a mailbox in each thread, and together they form a bi-directional link.

From SolarCapture 1.1 onwards it is not usually necessary to create mailboxes explicitly: They are created automatically when objects in different threads are connected together.

int sc_mailbox_connect ( struct sc_mailbox *  mb1,
struct sc_mailbox *  mb2 
)

Connect a pair of mailboxes.

Parameters
mb1The first mailbox.
mb2The second mailbox.
Returns
0 on success, or a negative error code.

Link a pair of mailboxes so that they can communicate. A mailbox can only be connected once.

struct sc_node* sc_mailbox_get_send_node ( struct sc_mailbox *  mailbox)

Return a mailbox's "send node".

Parameters
mailboxThe mailbox.
Returns
The mailbox's send-node. Packets passed to this send-node are forwarded to the paired mailboxes recv-node.
int sc_mailbox_poll ( struct sc_mailbox *  mailbox,
struct sc_packet_list list 
)

Poll a mailbox.

Parameters
mailboxThe mailbox to poll.
listReceived packets are appended to this list.
Returns
0 on success, or a negative error code.

This function should only be invoked on an unmanaged mailbox. It is necessary to poll a mailbox in order to receive packets from other threads, and to ensure that sent packets are delivered.

void sc_mailbox_send ( struct sc_mailbox *  mailbox,
struct sc_packet packet 
)

Send a packet through a mailbox to another thread.

Parameters
mailboxThe mailbox.
packetThe packet to send.

This function should only be invoked on an unmanaged mailbox.

Invoke this function to place a packet on a mailbox's send queue. NB. The packet may not actually be delivered to the remote thread until a later call to sc_mailbox_poll().

void sc_mailbox_send_list ( struct sc_mailbox *  mailbox,
struct sc_packet_list list 
)

Send a list of packets through a mailbox to another thread.

Parameters
mailboxThe mailbox.
listThe packets to send.

This function should only be invoked on an unmanaged mailbox.

Invoke this function to place packets on a mailbox's send queue. NB. The packets may not actually be delivered to the remote thread until a later call to sc_mailbox_poll().

int sc_mailbox_set_recv ( struct sc_mailbox *  mailbox,
struct sc_node node,
const char *  name_opt 
)

Connect a mailbox to a node.

Parameters
mailboxThe mailbox.
nodeThe node.
name_optOptional ingress port name (may be NULL).
Returns
0 on success, or a negative error code.

Connect the output of a mailbox to a node. Packets passed to the send-node of the paired mailbox are passed to node.