LWES - Light Weight Event System API for Ruby

• www.lwes.org

• sourceforge.net/projects/lwes

DESCRIPTION:

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.

FEATURES:

• easy-to-use, “Ruby-ish” API, no manual memory management

• optional ESF (event specification format) validation support

SUPPORT:

See the SourceForge project.

DEVELOPMENT:

Our SVN repository is here:

https://lwes.svn.sourceforge.net/svnroot/lwes/lwes-ruby

INSTALL:

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.

gem install lwes

SYNOPSIS:

require 'lwes'

# create an Emitter which may be used for the lifetime of your process
emitter = LWES::Emitter.new(:address => '224.1.1.11',
                            :port => 12345,
                            :heartbeat => 30, # nil to disable
                            :ttl => 1) # nil for no ttl

# parse your ESF file at startup, the example below assumes you
# have "Event1" and "Event2" defined in your ESF file:
type_db = LWES::TypeDB.new("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 = MyApp::Event1.new
my_event.started = Time.now.to_i
my_event.remote_addr = "192.168.0.1"
# ...do a lot of stuff here in between...
my_event.field1 = value1
my_event.field2 = value2
my_event.field3 = value3
my_event.finished = Time.now.to_i
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 # ...

NON-ESF USERS:

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 = LWES::Emitter.new(:address => '224.1.1.11',
                            :port => 12345,
                            :heartbeat => 30, # nil to disable
                            :ttl => 1) # nil for no ttl

# 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.now.to_i ],
  :time_usec => [ :int32, Time.now.tv_usec ],
  :remote_addr => [ :ip_addr, "192.168.0.1" ],
}

# 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