Proposed 1.0 semantics specification

[Scott James Remnant]

On Sun, 2009-06-14 at 15:57 -0400, Casey Dahlin wrote:

> This is my attempt to record and formalize Scott's description to me of 
> the way Upstart 1.0 should behave. Its not complete and need some 
> review, but there's a critical mass there now and I think its time to 
> draw attention to it.
> 
> http://upstart.ubuntu.com/wiki/CaseyDahlin/NewInternalSemantics
> 
Thanks Casey, this is a great start to discussion!  It's also a pretty
good way for me to read things I've said, and figure out where I've gone
wrong <g>

My notes/thoughts/ramblings below:


Events:
  Events are also generated during Job state changes, they carry the
same environment as the state.  This is probably where most events come
from.

  Semantically they look pretty similar:

  "while network-device eth0 up ADDRESS=xx:xx:xx:*"
  vs.
  "on network-device eth0 up ADDRESS=xx:xx:xx:*"

  The first matches the state, the second matches the event.


Configs:
  You call them Classe, which is what they're called in the 0.5 code ;)
Sometimes when I write them down, I call them Prototypes.

  I'm vaguely moving towards just calling them Configs, since they are
the object that directly represents the /etc/init/*.conf files.

  I wouldn't describe the config as having dependencies and start_on;
instead a better way to look at it might be that a config defines the
job creation criteria, and the start condition for a job.

  A class/config is exactly intended to be a template configuration for
a service.

  And yes, it's fully intended that a config doesn't actually need to
have any executable or daemon attached to it - and the resulting jobs
represent states of the system.


  Configs are never started or stopped, the only exposed method is to
create jobs from them.

  The D-Bus interface for that might look like:

    job =
Manager<com.ubuntu.Upstart.Manager>.CreateJobFromConfig("apache")

    conf = Manager<com.ubuntu.Upstart.Manager>.GetConfigByName("apache")
    job = conf<com.ubuntu.Upstart.Config>.CreateJob()



Commands like "initctl list" show the list of current *jobs*, not
configs.  "start" and "stop" take *jobs*, not configs.

The act of loading a config into Upstart will automatically create jobs
from it, as will state changes in the job creation criteria.

Consider the infamous "D-Bus interface to apache" example:

  /etc/init/apachedbd:
    while apache and dbus-daemon

When this is created, a job will be created for each possible pairing of
apache and dbus-daemon.

If we assume that these are both freshly created, there will be one job
each, so there is only one possible pairing.  Thus we have a single
apachedbd job available that will show up in the lists and can be
started/stopped.

(The single apache and dbus-daemon exist because of the exact same
 method, at some point there will be a job that has no "while" clause -
 they always get a job anyway)


If we now start the apache job, then start the dbus-daemon job, the
while condition is satisfied so the apachedbd job is started too
(because there is no "on" and the job is not in manual mode).

If we now create a *second* dbus-daemon job from the original config
(assumedly with a different bus address), we'll now have two possible
pairings of apache/dbus-daemon -- therefore a SECOND apachedbd job will
be created to match it.

When we start this *second* dbus-daemon job, our *second* apachedbd job
will be started along with it.

Both apachedbd will show up in job listings, and both can be started and
stopped manually.


Thus it is jobs (what you call instances) that have the Start and Stop
method, not the Config.


A few points:

 while specifies the job creation criteria and the ability to start
   criteria

 on specifies the start criteria

 a config without while always has a job created

 a job without while may always be started

 a job without on is always started when it can be

e.g.

  while foo
  on bar

  - will only be started if bar happens while foo

  while foo

  - will be running while foo

  on bar

  - will be started if bar happens anytime


States of jobs:

  pretty much the same as it is today, and as you describe.


Jobs:
  Restart isn't "stop then start", it's actually an immediate atomic
toggle of the state.  The job state is changed to stop, the process
begun and then immediately changed back to start.

  Effectively the same as a respawn, but with more murder-death-kill

  It's different from stop && startbecause it's atomic (ie. nothing else
can happen in between the two)


The Queue:
  Right now, the queue is for events only; not methods and it's only
really there to avoid excessive recursiveness.  Commands are not queued,
they are acted on immediately.

  Not sure whether this is right or not, of course <g>

Garbage Collection:
  I don't think you've got this right, instances are not nominally
destroyed - since they need to exist so they can be started on.

  Certainly its while clauses being in waiting is not a reason to be
destroyed, just a reason for that instance to remain in waiting itself.



Scott
-- 
Have you ever, ever felt like this?
Had strange things happen?  Are you going round the twist?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/upstart-devel/attachments/20090615/53d0489e/attachment.pgp