source: project/wiki/spread @ 12880

Last change on this file since 12880 was 12880, checked in by sjamaan, 11 years ago

Temporary hack to fix example sections in wiki eggdoc pages

File size: 8.8 KB
Line 
1[[tags: egg]]
2
3== spread
4
5[[toc:]]
6
7=== Description
8
9A library for using the [[http://www.spread.org|Spread]] multicast
10group communication system.
11
12=== Author
13
14[[felix winkelmann]]
15
16=== Requirements
17
18[[easyffi]]
19
20=== Download
21
22[[http://www.call-with-current-continuation.org/eggs/spread.egg|spread.egg]]
23
24=== Documentation
25
26You should be roughly familiar with the Spread system and it's API -
27this document does not attempt to explain Spread in every detail. For
28additional information see the [[http://www.spread.org|Spread website]].
29
30Spread has to be properly installed for this extension to work.
31
32These procedures return an unspecified value, unless documented
33otherwise. Should an invocation of the Spread API fail, a composite
34condition of the kinds {{(exn spread)}} will be signalled, with the
35additional property {{code}}, containing the spread error code.
36
37<procedure>(sp:connect [SPREAD-NAME] #!key PRIVATE-NAME PRIORITY GROUP-MEMBERSHIP)</procedure>
38
39Connects to a Spread daemon. {{SPREAD-NAME}} should be of the form
40{{"<port-number>"}} or
41{{"<port-number>@<host-name>"}}. {{PRIVATE-NAME}} is a string naming
42the connection (defaults to a randomly generated name) and should be
43unique on the machine running the daemon. If {{GROUP-MEMBERSHIP}} is
44given and not {{#f}}, then this connection will receive
45group-membership messages. {{PRIORITY}} is currently not used.  If
46{{SPREAD-NAME}} is not given it defaults to a string containing the
47default port for spread (usually 4803).
48
49Returns a connection object.
50
51<procedure>(sp:connection? X)</procedure>
52
53Returns {{#t}} if {{X}} is a connection object or {{#f}} otherwise.
54
55<procedure>(sp:connection-private-group CONNECTION)</procedure>
56
57Returns the private group name of this connection as assigned by the Spread daemon.
58
59<procedure>(sp:disconnect CONNECTION)</procedure>
60
61Terminates the connection. Note that a process may have multiple connections.
62
63<procedure>(sp:join CONNECTION GROUP)</procedure>
64
65Joins the group with the name {{GROUP}} (a string). If no group with
66this name exists, it is created.
67
68<procedure>(sp:leave CONNECTION GROUP)</procedure>
69
70Leaves the group with the name {{GROUP}} (a string). If the group does
71not exist, this operation is does nothing.
72
73<procedure>(sp:multicast CONNECTION SERVICE-TYPE GROUP MESSAGE #!key SELF-DISCARD MESSAGE-TYPE)</procedure>
74
75Sends a message to one or more groups. {{MESSAGE}} is a string
76containing the message to be sent, via {{CONNECTION}} and to the group
77or groups given in {{GROUP}} (either a string or a list of strings). The
78{{SERVICE-TYPE}} argument should be one of the symbols {{unreliable,
79reliable, fifo, causal, agreed}} or {{safe}} and specifies what kind
80of service is requested. {{MESSAGE-TYPE}} can be an arbitrary message code
81that Spread will send unchanged to all recipients.
82
83If {{SELF-DISCARD}} is given and true, then messages sent by this
84connection are not sent back to the sender (the same connection).
85
86<procedure>(sp:receive CONNECTION #!key MAX-GROUPS DROP-RECV MAX-MESSAGE-LENGTH DESTINATION)</procedure>
87
88Waits for a message from the Spread daemon on the given
89connection. {{MAX-GROUPS}} gives the maximal number of groups to be
90returned in the message object and defaults to
9116. {{MAX-MESSAGE-LENGTH}} gives the maximal size of the buffer
92receiving the message (defaults to 1024 bytes). DESTINATION is the
93buffer to store the message in. If no destination is given a new
94buffer will be allocated. If the received message is larger than the
95destination buffer and {{MAX-MESSAGE-LENGTH}} is not given, then the
96buffer will be automatically resized and the receive-operation will be
97repeated. If {{MAX-MESSAGE-LENGTH}} is given and the destination is
98too small, an error will be signalled.
99
100Returns a message object.
101
102'''FIXME: find explanation for {{DROP-RECV}}.'''
103
104<procedure>(sp:message X)</procedure>
105
106Returns {{#t}} if {{X}} is a message object or {{#f}} otherwise.
107
108<procedure>(sp:message-data MESSAGE)</procedure>
109
110Returns the contents of the message: either a string (if a regular
111message) or a list of groups (if a regular membership message).
112
113<procedure>(sp:message-endian-mismatch? MESSAGE)</procedure>
114
115Returns {{#t}} if the endianness of the sending machine differs from
116that of this receiving machine.
117
118<procedure>(sp:message-sender MESSAGE)</procedure>
119
120Returns the private group name of the sending connection or the group
121name, if a membership message.
122
123<procedure>(sp:message-groups MESSAGE)</procedure>
124
125A list of the names of all groups receiving this message.
126
127<procedure>(sp:message-service-type MESSAGE)</procedure>
128
129A list of symbols designating the type of this message. Possible members are:
130
131  unreliable
132  reliable
133  fifo
134  causal
135  agreed
136  safe
137  regular
138  regular-membership
139  transition
140  caused-by-join
141  caused-by-leave
142  caused-by-disconnect
143  caused-by-network
144  membership
145
146<procedure>(sp:message-type MESSAGE)</procedure>
147
148An arbitrary integer code sent with the message.
149
150<procedure>(sp:regular-message? MESSAGE)</procedure>
151
152Returns {{#t}} if the message is a regular (data) message, or {{#f}} otherwise.
153
154<procedure>(sp:regular-membership-message? MESSAGE)</procedure>
155
156Returns {{#t}} if the message is a regular membership (join/leave) message, or {{#f}} otherwise.
157
158<procedure>(sp:transitional-membership-message? MESSAGE)</procedure>
159
160Returns {{#t}} if the message is a ''transitional'' membership
161message, or {{#f}} otherwise.  (This is a message that designates a
162membership-change to be occurring in the future. Unfortunately this is
163not fully documented in the Spread manuals).
164
165<procedure>(sp:self-leave-message? MESSAGE)</procedure>
166
167Returns {{#t}} if the message is a membership (leave) message of this connection, or {{#f}} otherwise.
168
169<procedure>(sp:poll CONNECTION)</procedure>
170
171Returns {{#t}} if there is a message ready for receival (i.e. the next
172{{sp:receive}} will not block), or {{#f}} otherwise.
173
174<procedure>(sp:version)</procedure>
175
176Returns three values, the major- and minor version number of the used
177Spread library and its patch-level.
178
179=== Examples
180
181A simple sender/receiver pair:
182
183<examples><example>
184<init>(require-extension spread posix srfi-1)</init>
185<expr>
186; sender.scm
187
188(define c (sp:connect))
189(sp:join c "foobar")
190
191(define (print-message x)
192  (print "SENDER: " (sp:message-service-type x) " - " (sp:message-data x)) )
193
194(let loop ()
195  (sleep 1)
196  (sp:multicast c 'reliable "foobar" (->string (reverse (iota (random (add1 100))))))
197  (do () ((not (sp:poll c)))
198    (print-message (sp:receive c)) )
199  (loop) )
200</expr>
201</example></examples>
202
203<examples><example>
204<init>(require-extension spread)</init>
205<expr>
206; receiver.scm
207
208(define c (sp:connect))
209(sp:join c "foobar")
210
211(define (print-message x)
212  (print "RECEIVER: " (sp:message-service-type x) " - " (sp:message-data x)) )
213
214(let loop ()
215  (let ([msg (sp:receive c)])
216    (print-message msg)
217    (when (sp:regular-message? msg)
218      (let ([lst (with-input-from-string (sp:message-data msg) read)])
219        (assert (= (add1 (car lst)) (length lst))) ) )
220    (loop) ) )
221</expr>
222</example></examples>
223
224=== Changelog
225
226* 1.3 Removed use of {{___callback}}.
227* 1.2 The {{self-discard:}} keyword-argument to {{sp:multicast}} defaults to {{#t}}.
228* 1.1 Adapted to new FFI macro names
229* 1.0 Initial release
230
231=== License
232
233This product uses software developed by Spread Concepts LLC for use in the Spread toolkit.
234
235For more information about Spread see [[http://www.spread.org]]
236
237  Copyright (c) 2004, Felix L. Winkelmann
238  All rights reserved.
239 
240  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
241  conditions are met:
242 
243    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
244      disclaimer.
245    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
246      disclaimer in the documentation and/or other materials provided with the distribution.
247    Neither the name of the author nor the names of its contributors may be used to endorse or promote
248      products derived from this software without specific prior written permission.
249 
250  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
251  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
252  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
253  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
254  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
255  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
256  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
257  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
258  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.