DragonFly On-Line Manual Pages

Search: Section:  

SP_MULTICAST(3)                  User Manuals                  SP_MULTICAST(3)


NAME

       SP_multicast, SP_scat_multicast, SP_multigroup_multicast,
       SP_multigroup_scat_multicast - Multicast message to groups


SYNOPSIS

       #include <sp.h>

       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);


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 This 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 varients 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.


RETURN VALUES

       Returns the number of bytes sent on success or one of the following
       errors ( < 0 ):

       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 occured and the
               send could not be completed.


BUGS

       None.


AUTHOR

       Yair Amir <yairamir@cnds.jhu.edu>
       Jonathan Stanton <jonathan@cnds.jhu.edu>


SEE ALSO

       libspread(3)

SPREAD                             JULY 1998                   SP_MULTICAST(3)

Search: Section: