README

   1 = LWES - Light Weight Event System API for Ruby
   2
   3 * http://www.lwes.org
   4 * http://sourceforge.net/projects/lwes
   5
   6 == DESCRIPTION:
   7
   8 The LWES Light-Weight Event System is a framework for allowing the exchange of
   9 information from many machines to many machines in a controlled, platform
  10 neutral, language neutral way.  The exchange of information is done in a
  11 connectless fashion using multicast or unicast UDP, and using self describing
  12 data so that any platform or language can translate it to it's local dialect.
  13
  14 Instead of blindly using SWIG-generated bindings and exposing users to the
  15 underlying C APIs, we've wrapped the underlying C library bindings in an
  16 easy-to-use Ruby library.  Currently we only support emitting events but
  17 may support listening and journaling capabilities as time allows.
  18
  19 == FEATURES:
  20
  21 * easy-to-use, "Ruby-ish" API, no manual memory management
  22 * optional ESF (event specification format) validation support
  23
  24 == SUPPORT:
  25
  26 See the SourceForge project.
  27
  28 == SYNOPSIS:
  29
  30   require 'lwes'
  31
  32   # create an Emitter which may be used for the lifetime of your process
  33   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  34                               :port => 12345,
  35                               :heartbeat => 30, # nil to disable
  36                               :ttl => 1) # nil for no ttl
  37
  38   # parse your ESF file at startup, the example below assumes you
  39   # have "Event1" and "Event2" defined in your ESF file:
  40   type_db = LWES::TypeDB.new("my_events.esf")
  41
  42   # create classes to use, by default and to encourage DRY-ness,
  43   # we map each event in the ESF file to a class
  44   # Optionally, you may specify :parent => module/namespace
  45   type_db.create_classes! :parent => MyApp
  46
  47   # inside your application, you may now do this to slowly build up
  48   # fields for the event
  49   my_event = MyApp::Event1.new
  50   my_event.started = Time.now.to_i
  51   my_event.remote_addr = "192.168.0.1"
  52   # ...do a lot of stuff here in between...
  53   my_event.field1 = value1
  54   my_event.field2 = value2
  55   my_event.field3 = value3
  56   my_event.finished = Time.now.to_i
  57   emitter.emit my_event
  58
  59   # Alternatively, if you know ahead of time all the fields you want to
  60   # set for an event, you can emit an event in one step:
  61
  62   emitter.emit MyApp::Event2, :field1 => value1, :field2 => value2 # ...
  63
  64
  65 == NON-ESF USERS:
  66
  67 For prototyping and development, it may be easier to not use an ESF
  68 file.  In those cases, you may skip the TypeDB steps entirely and
  69 just use an emitter to send Hash objects:
  70
  71   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  72                               :port => 12345,
  73                               :heartbeat => 30, # nil to disable
  74                               :ttl => 1) # nil for no ttl
  75
  76   # Since we can't reliably map certain Ruby types to LWES types, you'll
  77   # have to specify them explicitly for IP addresses and all Integer
  78   # types.
  79   event = {
  80     :time_sec => [ :int32, Time.now.to_i ],
  81     :time_usec => [ :int32, Time.now.tv_usec ],
  82     :remote_addr => [ :ip_addr, "192.168.0.1" ],
  83   }
  84
  85   # Strings and Boolean values are easily mapped, however:
  86   event[:field1] = "String value"
  87   event[:boolean1] = true
  88   event[:boolean2] = false
  89
  90   # finally, we just emit the hash with any given name
  91   emitter.emit "Event3", event