README.md

   1 Light Weight Event System (LWES)
   2 ================================
   3 Click [here](http://lwes.github.io) for more information about lwes.
   4 For more information about using lwes from erlang read on.
   5
   6 Creating Events
   7 -------------------------
   8 There are 2 ways of creating events, the functional way
   9
  10 ```erlang
  11 Event0 = lwes_event:new ("MyEvent"),
  12 Event1 = lwes_event:set_uint16 (Event0, "MyUint16", 25),
  13 ```
  14
  15 or via records like
  16
  17 ```erlang
  18 Event = #lwes_event {
  19           name = "MyEvent",
  20           attrs = [{uint16, "MyUint16", 25}]
  21         },
  22 ```
  23
  24 Emitting to a single channel
  25 -------------------------
  26 If you are using multicast, or only want to emit to a single channel you
  27 can open it as follows
  28
  29 ```erlang
  30 {ok, Channel0} = lwes:open (emitter, {Ip, Port})
  31 Channel1 = lwes:emit (Channel0, Event1).
  32 ```
  33
  34 Emit to several channels
  35 -------------------------
  36 If you aren't using multicast but would like to emit to several machines,
  37 or groups of machines you can with slightly different config,
  38
  39 ```erlang
  40 % emit to 1 of a set in a round robin fashion
  41 {ok, Channels0} = lwes:open (emitters, {1, [{Ip1,Port1},...{IpN,PortN}]})
  42 Channels1 = lwes:emit (Channels0, Event1)
  43 Channels2 = lwes:emit (Channels1, Event2)
  44 ...
  45 lwes:close (ChannelsN)
  46
  47 % emit to 2 of a set in an m of n fashion (ie, emit to first 2 in list,
  48 % then 2nd and 3rd, then 3rd and 4th, etc., wraps at end of list)
  49 {ok, Channels0} = lwes:open (emitters, {2, [{Ip1,Port1},...{IpN,PortN}]})
  50 ```
  51
  52 Listening via callback
  53 -------------------------
  54 ```erlang
  55 {ok, Channel} = lwes:open (listener, {Ip, Port})
  56 lwes:listen (Channel, Fun, Type, Accum).
  57 ```
  58 Fun is called for each event
  59
  60 Type is one of
  61
  62 <table>
  63   <tr>
  64     <th>raw</th><td>callback is given raw udp structure, use lwes_event:from_udp to turn into event</td>
  65   </tr>
  66   <tr>
  67     <th>list</th><td>callback is given an #lwes_event record where the name is a binary, and the attributes is a proplist where keys are binaries, and values are either integers (for lwes int types), binaries (for lwes strings), true|false atoms (for lwes booleans), or 4-tuples (for lwes ip addresses)</td>
  68   </tr>
  69   <tr>
  70     <th>tagged</th><td>callback is given an #lwes_event record where the name is a binary, and the attributes are 3-tuples with the first element the type of data, the second the key as a binary and the third the values as in the list format</td>
  71   </tr>
  72   <tr>
  73     <th>dict</th><td>callback is given an #lwes_event record where the name is a binary, and the attributes are a dictionary with a binary key and value according to the type</td>
  74   </tr>
  75   <tr>
  76     <th>json</th><td>this returns a proplist instead of an #lwes_event record.  The valuse are mostly the same as list, but ip addresses are strings (as binary).  This should means you can pass the returned value to mochijson2:encode (or other json encoders), and have the event as a json document</td>
  77   </tr>
  78 </table>
  79
  80 Closing channel
  81 -------------------------
  82 ```erlang
  83 lwes:close (Channel)
  84 ```