README

   1 = LWES - Light Weight Event System bindings for Ruby
   2
   3 * http://www.lwes.org
   4 * git://rubyforge.org/lwes.git
   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 Email the author: mailto:erik.s.chang@gmail.com and expect a response
  27 within 72 hours.
  28
  29 == DEVELOPMENT:
  30
  31 Our git repository is here:
  32
  33   git clone git://rubyforge.org/lwes.git
  34
  35 Email pull requests or patches to the the author mailto:erik.s.chang@gmail.com
  36
  37 == INSTALL:
  38
  39 This library is easy to install, if you have the LWES library already
  40 installed you can use that, otherwise the RubyGems installer will
  41 automatically download and install a private copy only for use with your
  42 gem.
  43
  44   gem install lwes
  45
  46 == SYNOPSIS
  47
  48 See link:LWES.html
  49
  50 == NON-ESF USERS:
  51
  52 For prototyping and development, it may be easier to not use an ESF
  53 file.  In those cases, you may skip the TypeDB steps entirely and
  54 just use an emitter to send Hash objects:
  55
  56   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  57                               :port => 12345,
  58                               :heartbeat => 30, # nil to disable
  59                               :ttl => 1) # nil for default TTL(3)
  60
  61   # Since we can't reliably map certain Ruby types to LWES types, you'll
  62   # have to specify them explicitly for IP addresses and all Integer
  63   # types.
  64   event = {
  65     :time_sec => [ :int32, Time.now.to_i ],
  66     :time_usec => [ :int32, Time.now.tv_usec ],
  67     :remote_addr => [ :ip_addr, "192.168.0.1" ],
  68   }
  69
  70   # Strings and Boolean values are easily mapped, however:
  71   event[:field1] = "String value"
  72   event[:boolean1] = true
  73   event[:boolean2] = false
  74
  75   # finally, we just emit the hash with any given name
  76   emitter.emit "Event3", event