event 3plumb 2013-04-11

NAME

event - the event dispatcher

SYNPOSIS

event:* |

| event:*

 
                 +-------+
* (emitter) ---->|       |---> * (subscriber)
* (emitter) ---->| event |
* (emitter) --->|       |----> * (subscriber)
                 +-------+

DESCRIPTION

The event dispatcher is a [hub] initialized by the standard script during startup as follows:
 
event=[hub eof=ignore]
The purpose of the event dispatcher is to collect all events from plumb core, VPs and user processes and dispatch them to subscribers (user processes). This feature is useful for compelx scripts (often also employing [cmd]) for keeping track of process and fd states.Each record passed to the event dispatcher should be a single line of plain text. By convention the first word of events emitted by plumb (from core or from VPs) starts with "plumb_". Another convention is that VPs that need to emit events normally use their fd 4 for connecting to the event dispatcher.The user is free to generate events binding any source fd of RPs or VPs to the event dispatcher. None of the above conventions are mandatory for user events, but keeping one-line-per-record is recommended.Events emitted by plumb:
plumb_close %s:%d (emitted by: core) an fd is closed; %s is the ID of the process, %d is the fd number of the process
plumb_procwatch %s %s (emitted by: [procwatch]) status change of an RP; first %s is the ID of the process, second %s is "START" when the process starts or "END %s %d" when the process ends. In case of END %s is a reason ("EXIT" for normal exit, "ABNR" for abnormal exit (e.g. segmentation fault), "KILL" when the process is explicitly killed (SIGTERM, SIGKILL)) and %d is the exit code.
plumb_timer %d %s (emitted by [timer event ...]) %d is the number of repeats remaining, $s is the msg field of the timer if it was specified; happens only when "event" argument is set.
plumb_split %s buffer grew too large (emitted by [split event ...]) %s is the process ID; emitted by a [split] when the internal buffer grows too large (no separator for too long, for example "line too long" for line splitting); emitted only if "event" is specified for [split]

eof handling

Ignores eof.

blocking/flow control

Default.

buffering

None.

EXAMPLE

 
foo={my_command}
event:* | env:1
will run RP foo and print events generated at start/stop, normally:
 
plumb_procwatch foo START
plumb_procwatch foo END EXIT 0

SEE ALSO

event 3plumb 2013-04-11