lib/spread_drv/UserGuide.txt

   1
   2 Sorry, this isn't much of a user guide, but hopefully it's better than
   3 nothing.
   4
   5
   6 Prerequisites
   7 =============
   8
   9 * I strongly recommend that your Erlang virtual machine executable,
  10   "beam", has been compiled with threads support.  The Spread driver
  11   attempts to utilize a pool of worker threads, if they are available,
  12   to avoid blocking the entire virtual machine.  Without additional
  13   worker threads, all other Erlang processes may be frozen when
  14   calling certain Spread driver functions.
  15
  16   If you see the string "threads" when you run "erl":
  17
  18     % erl
  19     Erlang (BEAM) emulator version 5.2.3.3 [source] [threads:0]
  20
  21     Eshell V5.2.3.3  (abort with ^G)
  22     1>
  23
  24   ... then your "beam" executable supports threads.  If you don't see
  25   "threads" in the banner line, then you should re-run "configure" and
  26   then re-compile and re-install.
  27
  28   At the top level directory of the Erlang OTP source distribution,
  29   include the flag "--enable-threads" on the "configure" command
  30   line.  For example:
  31
  32     % ./configure --prefix=/usr/local --enable-threads
  33
  34 * In order to take advantage of the threads, you'll need to include
  35   the flag "+Ax" on the "erl" command line.  Replace "x" with a number
  36   greater than zero.  For example, to create a pool of 8 worker
  37   threads:
  38
  39     % erl +A8
  40     Erlang (BEAM) emulator version 5.2.3.3 [source] [threads:8]
  41
  42     Eshell V5.2.3.3  (abort with ^G)
  43     1>
  44
  45 * You must have the Spread library compiled and installed on your
  46   system.  This driver is known to work with version 3.17.0 of
  47   Spread.  The source can be obtained from http://www.spread.org/.
  48
  49   If you are building this driver as part of the EDTK source
  50   distribtion, edit the Makefile for the paths to the "sp.h" C header
  51   file and the libtspread.so shared library file.  If you're building
  52   it as part of the Jungerl source collection, see the "README" file
  53   in this directory for compilation instructions.
  54
  55 * You must have at least one machine running a properly-configured
  56   Spread daemon.  See the Spread documentation for creating a suitable
  57   "spread.conf" configuration file for your environment and for
  58   starting the daemon.
  59
  60   The "spuser" tool, included with the Spread source distribution, can
  61   be very helpful in debugging Spread daemon configuration problems.
  62   If you can run "spuser" on two different machines (with two properly
  63   configured Spread daemons), or on a single machine (with a single
  64   properly configured Spread daemon), then "j foo" to join the group
  65   "foo", and you see the results, you've got the daemons properly
  66   configured.
  67
  68 * You ought know how the Spread API works.  It will be very useful to
  69   know the basics of the C version or the Java version.  The Spread
  70   User Guide is probably the best place to look; it can be found at
  71   http://www.spread.org/docs/docspread.html
  72
  73
  74 What source files do what?
  75 ==========================
  76
  77 spread.erl
  78
  79         This is a high-level interface to the Spread driver.  The
  80         operations is provides are:
  81
  82         - start_link: Start a spread intermediary process.  It's
  83           possible to have several running inside the same virtual
  84           machine, but it's probably better to share a single one.
  85           Unless you have a specific reason for wanting multiple ones:
  86           each intermediary process will open a spread_drv driver
  87           port, which in turn issue a single connection to a Spread
  88           daemon.
  89
  90         - stop: Stop the spread intermediary process.
  91
  92         - subscribe: Subscribe to messages sent to a particular Spread
  93           group.  You have the option of asking for messages that
  94           reflect changes in membership of the group.
  95
  96           NOTE: Not all data that is present in the raw Spread
  97           membership event message (e.g., the Spread group ID number,
  98           the reason for the membership change, who was added/removed)
  99           is available in the current Erlang implementation.  Adding
 100           those things would be straightforward, but it isn't clear if
 101           anyone/anything needs them right now.
 102
 103         - unsubscribe: Cancel a previous subscription.
 104
 105         - multicast: Send a message to a Spread group.  You are not
 106           required to subscribe to the group first.  However, if you
 107           are subscribed to the group, then you will receive a copy of
 108           the message.
 109
 110         - mg_multicast: Send a message to several Spread groups
 111           simultaneously.
 112
 113         Once subscribed to a Spread group, your mailbox will receive
 114         one or two types messages from the Spread intermediary:
 115
 116         - {spread, Pid, membership, Group, Members}
 117
 118           This message notifies you that the membership of group Group
 119           has changed to the list of Members.
 120
 121         - {spread, Pid, msg, Group, Type, Sender, MessType, Mess}
 122
 123           This message contains a message Mess from group Group.
 124           Type, Sender, MessType, and Mess all correspond closely to
 125           the Spread C API.  The only difference is that Type is not
 126           the C API's "service_type" bitmask but rather one of the
 127           following atoms:
 128
 129             unreliable_mess, reliable_mess, fifo_mess, causal_mess,
 130             agreed_mess, safe_mess
 131
 132 spread_drv.erl
 133
 134         This file is automatically generated by the Erlang Driver
 135         Toolkit (EDTK).  See http://www.snookles.com/erlang/edtk/ for
 136         the EDTK source code distribution, if you're curious.
 137
 138         There is a (almost) one-to-one correspondance between
 139         functions found in this file and the functions of the Spread C
 140         API as well as a nearly one-to-one mapping of the arguments
 141         between the Erlang functions and the C API's function
 142         arguments.  See the file "spread_drv.hrl" for constants and
 143         other magic numbers that are used by the driver.
 144
 145 spread_floodrec.erl
 146
 147         A simple application using the interface found in spread.erl.
 148         It acts as a passive collector of Spread messages, printing a
 149         short message each time that 1,000 messages have been
 150         received.
 151
 152         Run the following on machine A:
 153
 154         % erl +A5
 155         Erlang (BEAM) emulator version 5.2.3.3 [source] [threads:5]
 156
 157         Eshell V5.2.3.3  (abort with ^G)
 158         1> {ok, Pid} = spread_floodrec:start_link("flooder").
 159         {ok,<0.32.0>}
 160         Msg count = 1000
 161         Msg count = 2000
 162         Msg count = 3000
 163         Msg count = 4000
 164         Msg count = 5000
 165         2>
 166
 167         Run the following on machine B.  If you only have Spread set
 168         up on a single machine, run this on machine B ... it's just a
 169         bit less impressive that way.
 170
 171         % spflooder -m 5000 -b 4
 172         flooder: connecting to 4803@localhost
 173         flooder: starting  multicast of 5000 messages, 4 bytes each.
 174         flooder: completed   1000 messages of 4 bytes
 175         flooder: completed   2000 messages of 4 bytes
 176         flooder: completed   3000 messages of 4 bytes
 177         flooder: completed   4000 messages of 4 bytes
 178         flooder: completed   5000 messages of 4 bytes
 179         flooder: completed multicast of 5000 messages, 4 bytes each.
 180
 181 spread_test.erl
 182
 183         This is a set of extremely thin regression tests for the
 184         spread_drv driver.  I think of them as "smoke tests": give it
 185         a try, and see if smoke comes out.  The best way to run these
 186         tests is to use the command "make test" or "make regression".
 187