Light Weight Event System Ruby library
Ruby C
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= LWES - Light Weight Event System API for Ruby



The LWES Light-Weight Event System is a framework for allowing the exchange of
information from many machines to many machines in a controlled, platform
neutral, language neutral way.  The exchange of information is done in a
connectless fashion using multicast or unicast UDP, and using self describing
data so that any platform or language can translate it to it's local dialect.

Instead of blindly using SWIG-generated bindings and exposing users to the
underlying C APIs, we've wrapped the underlying C library bindings in an
easy-to-use Ruby library.  Currently we only support emitting events but
may support listening and journaling capabilities as time allows.


* easy-to-use, "Ruby-ish" API, no manual memory management
* optional ESF (event specification format) validation support


See the SourceForge project.


Our SVN repository is here:


This library is easy to install, if you have the LWES library already
installed you can use that, otherwise the RubyGems installer will
automatically download and install a private copy only for use with your

  gem install lwes


  require 'lwes'

  # create an Emitter which may be used for the lifetime of your process
  emitter = => '',
                              :port => 12345,
                              :heartbeat => 30, # nil to disable
                              :ttl => 1) # nil for default TTL(3)

  # parse your ESF file at startup, the example below assumes you
  # have "Event1" and "Event2" defined in your ESF file:
  type_db ="my_events.esf")

  # create classes to use, by default and to encourage DRY-ness,
  # we map each event in the ESF file to a class
  # Optionally, you may specify :parent => module/namespace
  type_db.create_classes! :parent => MyApp

  # inside your application, you may now do this to slowly build up
  # fields for the event
  my_event =
  my_event.started =
  my_event.remote_addr = ""
  # a lot of stuff here in between...
  my_event.field1 = value1
  my_event.field2 = value2
  my_event.field3 = value3
  my_event.finished =
  emitter << my_event

  # Alternatively, if you know ahead of time all the fields you want to
  # set for an event, you can emit an event in one step:

  emitter.emit MyApp::Event2, :field1 => value1, :field2 => value2 # ...


For prototyping and development, it may be easier to not use an ESF
file.  In those cases, you may skip the TypeDB steps entirely and
just use an emitter to send Hash objects:

  emitter = => '',
                              :port => 12345,
                              :heartbeat => 30, # nil to disable
                              :ttl => 1) # nil for default TTL(3)

  # Since we can't reliably map certain Ruby types to LWES types, you'll
  # have to specify them explicitly for IP addresses and all Integer
  # types.
  event = {
    :time_sec => [ :int32, ],
    :time_usec => [ :int32, ],
    :remote_addr => [ :ip_addr, "" ],

  # Strings and Boolean values are easily mapped, however:
  event[:field1] = "String value"
  event[:boolean1] = true
  event[:boolean2] = false

  # finally, we just emit the hash with any given name
  emitter.emit "Event3", event