CONCEPTUAL OVERVIEW
===================

EVENTS

Events are things that occur at a point in time

Events are named (one string)

Events carry additional parameters (zero or more parameter name -
parameter value pairs where the names and values are strings and the
names are distinct)

Events may be originated by
	- upstart due to statevar changes
	- initctl
	- upstart config


STATEVARS

Have a name (one string)

Have a state (a string) at each point in time

If no state yet set, state is the empty string

May be defined by abstract state machines, jobs, or implicitly by
reference and set with `set' or `initctl'.

Whenever the state changes, an event is generated; the event has the
same name as the statevar one parameter, <statevar>=<state>

Every possible statevar is taken to exist; ones that haven't
been set have the state `'.


STATE MACHINES (MACHINES)

May be
	- abstract state machines
	- jobs (control one or more processes)

Define/reference an identically-named statevar

Defined by an upstart config file leafnamed <machine>
	or which says   machine <machine>
		

JOBS

A job is a state machine with defscript or defexec directives

It references a statevar <job>/goal whose value must be `start' or
`stop' and which starts out as `stop' (instead of `')

It generates a statevar <job> whose value is one of
	stopped starting started stopping
and which may not be set other than by upstart.



CONFIG SYNTAX AND SEMANTICS
===========================


LEXICAL SYNTAX
 file is series of lines
 #-comments
 \-continuation
 tokens are generally whitespace-separated words or `='
  (unquoted string tokens do not contain punctuation other than `-' `_'
   `.' `/' and any other than `=' `#' `\' is currently a syntax error)
 unquoted strings may be keywords or values (eg, identifiers, globs, etc.)
 ""-quoted strings are identifiers or globs etc.
      ""-quoted strings may contain \" and \\
      when a ""-quoted string is a glob the un-dequoted innards are
        used as the glob pattern (so we only have one lot of \-removal)
        except that \" is replaced with " and \$ with $
 glob patterns match . at start
 glob patterns may contain [..] [^...] * ? and use \-quoting too


FILES

Each file defines a state machine whose name is <machine>; if there
are defscript or defexec directives it's a job.


CONTEXT DIRECTIVE

 machine <machine>	as if rest of file were another file
				with leafname <machine>

ENTRYPOINT DIRECTIVES

 on <event pattern> [as <export id>] [when <condition>]
 when <condition>   (happens when <condition> goes from false to true)
 defstate <label>
 label <label>

OTHER DIRECTIVES

 wait until <condition>
 wait for <event pattern> [as <export id>] [when <condition>]
 set <statevar> [<value> ...]  (default is `true')
 unset <statevar>	(sets to empty string)
 start|stop [<job>]     (same as  set <job>/goal start|stop)
 trigger <event> [<valstring> ...]
 export <statevar> [as <export id>]
 goto <label>


EVENT PATTERNS

 <event pattern> := <event glob> [or <event-glob> ...]
 <event glob> := <event name glob> \
	[<parameter name>=<parameter value glob> ...]
 
 which matches iff the globs match the event's name and values;
  list of valstring globs has zero or more `*' appended, and list of
  actual valstrings has zero or more `' appended, so that lists are
  same length.


CONDITIONS

 <condition> :=
	(<condition>)
	<condition> or <condition>
	<condition> and <condition>
	not <condition>
	<statevar name>				(`' is false; others are true)
	<statevar name> <statevar valstring glob>	(see for event globs)

JOBS

 defexec pre-start|post-start|pre-stop|post-stop|start|respawn|daemon \
						<program> <arg...>
	runs	<program> <arg...>  exactly

 defscript pre-start|... [<EOF>]
   <script>
 endscript       (or defined <EOF>)
	runs   sh -c <script> <job>/pre-start
				^this is $0

 in each case environment contains
  for `on' and each `wait for'
	UPST=<event name>
	UPST_<event name>_<param name>=<param value>
    except that if `export' is used
        <export id>=<event name>
	<export id>_<param name>=<param value>
  for every statevar mentioned in any <condition> or `export' directive
	UPST_<statevar>=<value>
    except that if `export' is used
	<export id>=<value>

 the relevant directives and conditions are
   the last `on' or `when' directive
   and all directives executed since then


SYNTHETIC EVENTS

upstart generates `startup' on startup

upstart generates
	<job>/failed \
		program=pre-start|pre-stop|... \
		exitstatus=<exit status>|SIG<foo>
 as appropriate.  note that daemon (but not respawn) exiting 0 is a failure


SEMANTICS OF STATE MACHINES

Each <machine> has one notional program counter, which may be nowhere
or at a particular `wait' line.

Whenever an `on' or `whenever' happens, or a `goto' is executed, the
program counter is reset to the relevant location and we start
executing.

When the program counter reaches `on', `whenever' or `defstate', we
stop executing (program counter set to nowhere) (this is the
difference between defstate and label).