Spread C API | SP

www.spread.org

Spread 3.17.3 C API

SP_multicast

int SP_multicast (mailbox mbox, service service_type, 
                  const char *group, int16 mess_type,
                  int mess_len, const char *mess); 

int SP_scat_multicast (mailbox mbox, service service_type,const 
                       char *group,int16 mess_type, 
                       const scatter *scat_mess);

int SP_multigroup_multicast (mailbox mbox, service service_type, int num_groups,
                             const char groups[][MAX_GROUP_NAME], int16 mess_type,
                             int mess_len, const char *mess);

int SP_multigroup_scat_multicast (mailbox mbox, service service_type, 
                                  int num_groups, const char groups[][MAX_GROUP_NAME], 
                                  int16 mess_type, const scatter *scat_mess);

Parameters

	mbox	connection handle to multicast message on
	service_type	set to the service this message requires
	group	specify the group destination for the message
	num_groups	used in multigroup_multicast to specify the number of groups the message should be sent to
	groups	used in multigroup_multicast to specify multiple group destinations for the message
	mess_type	application defined tag
	mess_len	length of message body
	mess	buffer to message
	scat_mess	message body (scatter structure)

Return Values

	>= 0	On success, sp_multicast returns the number of bytes sent
	ILLEGAL_SESSION	The mbox given to multicast on was illegal
	ILLEGAL_MESSAGE	The message had an illegal structure, like a scatter not filled out correctly
	CONNECTION_CLOSED	During communication to send the message errors occurred and the send could not be completed

Description

SP_multicast and its variants all can multicast send a message to one or more groups. The message is sent on a particular connection and is marked as having come from the connection who sent it.

The service_type is a type field that should be set to the service this message requires. The valid flags for messages are:

UNRELIABLE_MESS
RELIABLE_MESS
FIFO_MESS
CAUSAL_MESS
AGREED_MESS
SAFE_MESS

This type can be bit ORed with other flags like SELF_DISCARD if desired. Currently SELF_DISCARD is the only additional flag.

If the SP_multicast or SP_scat_multicast versions are being used then only one group can be sent to. So the group string should include the name of the group to send to. If a multigroup varient is being used then the groups are specified by the num_groups integer and the array of group names called groups representing all the groups the message should be sent to. Each group has a string name of no more then MAX_GROUP_NAME chars. The array should have at least as many group names as the 'num_groups' parameter indicates. The Spread system will only send the message once but will deliver it to all connections which have joined at least one of the groups listed.

The mess_type is a SHORT int (16 bits) which can be used by the application arbitrarily. The intent is that it could be used to NAME different kinds of data messages so they can be differentiated without looking into the body of the message. This value will be endian corrected before receiving.

If the non-scatter variants are being used then a single buffer is passed to the multicast call specifying the full message to be sent. The mess_len field gives the length in bytes of the message. While the mess field is a pointer to the buffer containing the message. For a scatter call, both of these are replaced with one pointer, scat_mess, to a scatter structure, which is just like an iovec. This allows messages made up of several parts to be sent without an extra copy on systems which support scatter-gather.

Currently SP_multicast can support messages sizes up to ~100Kbytes. See the Spread mailing list for more discussions on this topic and how to increase this limit..

Requirements

Header: Include sp.h
Library: Use libspread or libtspread
Version: 3.17.3

Also See

SP_receive