back

spread

Description:

A library for using the Spread multicast group communication system.

Author:

felix.

Version:

Usage:

(require-extension spread)

Download:

spread.egg

Documentation:

You should be roughly familiar with the Spread system and it's API - this document does not attempt to explain Spread in every detail. For additional information see the Spread website.
Spread has to be properly installed for this extension to work.

These procedures return an unspecified value, unless documented otherwise. Should an invocation of the Spread API fail, a composite condition of the kinds (exn spread) will be signalled, with the additional property code, containing the spread error code.

(procedure) (sp:connect [SPREAD-NAME] #!key PRIVATE-NAME PRIORITY GROUP-MEMBERSHIP)

Connects to a Spread daemon. SPREAD-NAME should be of the form "<port-number>" or "<port-number>@<host-name>". PRIVATE-NAME is a string naming the connection (defaults to a randomly generated name) and should be unique on the machine running the daemon. If GROUP-MEMBERSHIP is given and not #f, then this connection will receive group-membership messages. PRIORITY is currently not used. If SPREAD-NAME is not given it defaults to a string containing the default port for spread (usually 4803).
Returns a connection object.

(procedure) (sp:connection? X)

Returns #t if X is a connection object or #f otherwise.

(procedure) (sp:connection-private-group CONNECTION)

Returns the private group name of this connection as assigned by the Spread daemon.

(procedure) (sp:disconnect CONNECTION)

Terminates the connection. Note that a process may have multiple connections.

(procedure) (sp:join CONNECTION GROUP)

Joins the group with the name GROUP (a string). If no group with this name exists, it is created.

(procedure) (sp:leave CONNECTION GROUP)

Leaves the group with the name GROUP (a string). If the group does not exist, this operation is does nothing.

(procedure) (sp:multicast CONNECTION SERVICE-TYPE GROUP MESSAGE #!key SELF-DISCARD MESSAGE-TYPE)

Sends a message to one or more groups. MESSAGE is a string containing the message to be sent, via CONNECTION and to the group or groups given in GROUP (either a string or a list of strings). The SERVICE-TYPE argument should be one of the symbols unreliable, reliable, fifo, causal, agreed or safe and specifies what kind of service is requested. MESSAGE-TYPE can be an arbitrary message code that Spread will send unchanged to all recipients.
If SELF-DISCARD is given and true, then messages sent by this connection are not sent back to the sender (the same connection).

(procedure) (sp:receive CONNECTION #!key MAX-GROUPS DROP-RECV MAX-MESSAGE-LENGTH DESTINATION)

Waits for a message from the Spread daemon on the given connection. MAX-GROUPS gives the maximal number of groups to be returned in the message object and defaults to 16. MAX-MESSAGE-LENGTH gives the maximal size of the buffer receiving the message (defaults to 1024 bytes). DESTINATION is the buffer to store the message in. If no destination is given a new buffer will be allocated. If the received message is larger than the destination buffer and MAX-MESSAGE-LENGTH is not given, then the buffer will be automatically resized and the receive-operation will be repeated. If MAX-MESSAGE-LENGTH is given and the destination is too small, an error will be signalled.
Returns a message object.
FIXME: find explanation for DROP-RECV.

(procedure) (sp:message X)

Returns #t if X is a message object or #f otherwise.

(procedure) (sp:message-data MESSAGE)

Returns the contents of the message: either a string (if a regular message) or a list of groups (if a regular membership message).

(procedure) (sp:message-endian-mismatch? MESSAGE)

Returns #t if the endianness of the sending machine differs from that of this receiving machine.

(procedure) (sp:message-sender MESSAGE)

Returns the private group name of the sending connection or the group name, if a membership message.

(procedure) (sp:message-groups MESSAGE)

A list of the names of all groups receiving this message.

(procedure) (sp:message-service-type MESSAGE)

A list of symbols designating the type of this message. Possible members are: 



unreliable

reliable

fifo

causal

agreed

safe

regular

regular-membership

transition

caused-by-join

caused-by-leave

caused-by-disconnect

caused-by-network

membership
(procedure) (sp:message-type MESSAGE)

An arbitrary integer code sent with the message.

(procedure) (sp:regular-message? MESSAGE)

Returns #t if the message is a regular (data) message, or #f otherwise.

(procedure) (sp:regular-membership-message? MESSAGE)

Returns #t if the message is a regular membership (join/leave) message, or #f otherwise.

(procedure) (sp:transitional-membership-message? MESSAGE)

Returns #t if the message is a transitional membership message, or #f otherwise. (This is a message that designates a membership-change to be occurring in the future. Unfortunately this is not fully documented in the Spread manuals).

(procedure) (sp:self-leave-message? MESSAGE)

Returns #t if the message is a membership (leave) message of this connection, or #f otherwise.

(procedure) (sp:poll CONNECTION)

Returns #t if there is a message ready for receival (i.e. the next sp:receive will not block), or #f otherwise.

(procedure) (sp:version)

Returns three values, the major- and minor version number of the used Spread library and its patch-level.

Examples:

A simple sender/receiver pair: 
; sender.scm

(require-extension spread posix srfi-1)

(define c (sp:connect))
(sp:join c "foobar")

(define (print-message x)
  (print "SENDER: " (sp:message-service-type x) " - " (sp:message-data x)) )

(let loop ()
  (sleep 1)
  (sp:multicast c 'reliable "foobar" (->string (reverse (iota (random (add1 100))))))
  (do () ((not (sp:poll c)))
    (print-message (sp:receive c)) )
  (loop) )


; receiver.scm

(require-extension spread)

(define c (sp:connect))
(sp:join c "foobar")

(define (print-message x)
  (print "RECEIVER: " (sp:message-service-type x) " - " (sp:message-data x)) )

(let loop ()
  (let ([msg (sp:receive c)])
    (print-message msg)
    (when (sp:regular-message? msg)
      (let ([lst (with-input-from-string (sp:message-data msg) read)])
	(assert (= (add1 (car lst)) (length lst))) ) )
    (loop) ) )

License:

This product uses software developed by Spread Concepts LLC for use in the Spread toolkit.
For more information about Spread see http://www.spread.org 

Copyright (c) 2004, Felix L. Winkelmann
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 the author 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 HOLDERS 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.
back