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 == INSTALL:
  29
  30 This library is easy to install, if you have the LWES library already
  31 installed you can use that, otherwise the RubyGems installer will
  32 automatically download and install a private copy only for use with your
  33 gem.
  34
  35   gem install lwes
  36
  37 == SYNOPSIS:
  38
  39   require 'lwes'
  40
  41   # create an Emitter which may be used for the lifetime of your process
  42   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  43                               :port => 12345,
  44                               :heartbeat => 30, # nil to disable
  45                               :ttl => 1) # nil for no ttl
  46
  47   # parse your ESF file at startup, the example below assumes you
  48   # have "Event1" and "Event2" defined in your ESF file:
  49   type_db = LWES::TypeDB.new("my_events.esf")
  50
  51   # create classes to use, by default and to encourage DRY-ness,
  52   # we map each event in the ESF file to a class
  53   # Optionally, you may specify :parent => module/namespace
  54   type_db.create_classes! :parent => MyApp
  55
  56   # inside your application, you may now do this to slowly build up
  57   # fields for the event
  58   my_event = MyApp::Event1.new
  59   my_event.started = Time.now.to_i
  60   my_event.remote_addr = "192.168.0.1"
  61   # ...do a lot of stuff here in between...
  62   my_event.field1 = value1
  63   my_event.field2 = value2
  64   my_event.field3 = value3
  65   my_event.finished = Time.now.to_i
  66   emitter.emit my_event
  67
  68   # Alternatively, if you know ahead of time all the fields you want to
  69   # set for an event, you can emit an event in one step:
  70
  71   emitter.emit MyApp::Event2, :field1 => value1, :field2 => value2 # ...
  72
  73
  74 == NON-ESF USERS:
  75
  76 For prototyping and development, it may be easier to not use an ESF
  77 file.  In those cases, you may skip the TypeDB steps entirely and
  78 just use an emitter to send Hash objects:
  79
  80   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  81                               :port => 12345,
  82                               :heartbeat => 30, # nil to disable
  83                               :ttl => 1) # nil for no ttl
  84
  85   # Since we can't reliably map certain Ruby types to LWES types, you'll
  86   # have to specify them explicitly for IP addresses and all Integer
  87   # types.
  88   event = {
  89     :time_sec => [ :int32, Time.now.to_i ],
  90     :time_usec => [ :int32, Time.now.tv_usec ],
  91     :remote_addr => [ :ip_addr, "192.168.0.1" ],
  92   }
  93
  94   # Strings and Boolean values are easily mapped, however:
  95   event[:field1] = "String value"
  96   event[:boolean1] = true
  97   event[:boolean2] = false
  98
  99   # finally, we just emit the hash with any given name
 100   emitter.emit "Event3", event