Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

spread
  1. Outdated egg!
  2. spread
    1. Description
    2. Author
    3. Requirements
    4. Download
    5. Documentation
    6. Examples
    7. Changelog
    8. License

Description

A library for using the Spread multicast group communication system.

Author

felix winkelmann

Requirements

easyffi

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

Changelog

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.