[RFC] Event prefixing policy

Tue Feb 12 19:42:43 UTC 2013

On 02/12/2013 11:59 AM, James Hunt wrote:
> Hi Steve,
> 
> On 12/02/13 06:48, Steve Langasek wrote:
>> Hi James,
>>
>> On Thu, Jan 31, 2013 at 08:25:08PM +0000, James Hunt wrote:
>>
>>> For Enhanced User Sessions in Upstart, we originally planned for session
>>> jobs being supervised by a Session Init (upstart running as a non-priv
>>> user) to react to *both* system events and session events when the 'start
>>> on' stanza is specified in the usual form:
>>
>>>   start on foo
>>
>>> However, we now feel that this is likely to be a cause of some confusion since
>>> if there were jobs at both the system (pid 1) level *and* the user level that
>>> reacted to that event, the 'foo' event would cause both of them to start. This
>>> may or may not be desirable :) ...
>>
>>> /etc/init/bar.conf:
>>>    start on foo
>>
>>> $HOME/.config/upstart/bar.conf:
>>>    start on foo
>>
>>> $ sudo initctl emit foo   # OUTCOME: *both* bar jobs start.
>>> $ initctl emit foo        # OUTCOME: only user job starts
>>
>>> To avoid confusion, there are 2 approaches we're looking at (if you can
>>> think of others, please speak up):
>>
>> I think those are the main two approaches to consider.
>>
>>> (1) Require session jobs to specify the ':sys:' prefix to react to system
>>> events (no prefix or ':user:' would therefore match user events).
>>
>>>   start on :sys:foo  # start if 'foo' event emitted at PID 1 level.
>>>   start on foo       # start if 'foo' event emitted at Session Init level.
>>>   start on :user:foo # start if 'foo' event emitted at Session Init level.
>>
>>> (2) Require session jobs to specify the ':user:' prefix to react to user events
>>> (no prefix or ':sys:' would therefore match system events).
>>
>>>   start on :user:foo # start if 'foo' event emitted at Session Init level.
>>>   start on foo       # start if 'foo' event emitted at PID 1 level.
>>>   start on :sys:foo  # start if 'foo' event emitted at PID 1 level.
>>
>> I would argue against allowing two different syntaxes for the same thing. 
>> If 'start on foo' is unambiguous, it should also be the only way to write it
>> - whichever of :sys: and :user: is not required for disambiguation should be
>> prohibited altogether.
>>
>>> Option (1) has the virtue of being explicit so there is no doubt about
>>> what is being requested.  This probably wins wrt the Principle of Least
>>> Astonishment, but may be unwieldy if users have more jobs reacting to
>>> system events that session events (*).
>>
>>> Option (2) has the virtue that it would allow users to develop a job, test
>>> it via a Session Init and then deploy as a system job with no syntax
>>> change.  Since we imagine session jobs may wish to react to udev messages,
>>> this would simplify the jobs and make them compatible with system-level
>>> jobs.  Compare:
>>
>>>   start on      net-device-added INTERFACE=eth0
>>>   start on :sys:net-device-added INTERFACE=eth0
>>
>> Option 2 is certainly my preference in terms of semantics, though it may
>> make the implementation hairier than we might like (since the session init
>> then has to treat the bridged events specially, by *not* adding a prefix to
>> their names).

I personally prefer Option 1 as it's actually what we have currently in
trunk and doesn't require any explicit change to upstart as it's the
bridge which currently prefixes the events.

I only worked a bit on user jobs at this point, but I don't expect we'll
be using :sys: all that much, so having to prefix everything with :user:
as we'd have to for Option 2 seems like a bit of a pain for no obvious gain.

>>> If a user _really_ wants a job to react to both system- and user-level
>>> events, we could change the meaning of the '::' prefix to mean 'match all
>>> prefixes'.  This is probably clearer than making the 'no prefix' mean
>>> 'match all prefixes' since the extra syntactical sugar gives some
>>> indication that this isn't a normal event match.
>>
>> I don't think 'match all prefixes' is really useful for user jobs; a job
>> author should really know already where the event is going to come from.
>> The only way I see this being /potentially/ useful is to improve portability
>> of jobs between user and system init, /if/ system init supported the same
>> syntax - but I don't think that's really a good idea either.  Again, I think
>> it's better to not allow more than one way to specify the same event as this
>> is likely to just cause confusion.
>>
>> In lp:~jamesodhunt/upstart/event-prefixes, I see that you've opted for
>> option 1) above.  Maybe you could elaborate on why you preferred this
>> approach?
> My current branch does indeed favour option 1 since:
> 
> - it's less surprising I think that no prefix means 'my current namespace'.
> - the ':sys:' prefix is explicit and even if you haven't read the man pages
> hints that its referencing something out of the ordinary (outside the current
> namespace).
> 
> To some extent, I think we should consider the relative proportion of user jobs
> that we envisage would need to reference system events. As a data point,
> Stéphanes branch of planned default user jobs currently doesn't (need to) make
> any mention of system events but certainly makes use of user events.

Actually, I'll have to for one of the jobs, the event bridge itself
should only start if the system bus is available, so I'll need a "start
on started :sys:dbus" and have something that sends me that event as
it'll have been emitted long before we start the user session.

But yeah, besides that specific case, I haven't had to use any system
event at this point besides for a few personal jobs I wrote that react
on udev events (brightness changes) but I think it's perfectly
reasonable to have those use the :sys: prefix.
This makes the jobs very easy to understand and I think in general, a
user is more likely to understand the meaning of ":sys:" than they are
of ":user:", unless they're already pretty familiar with our
architecture that's.

> The standard user jobs can of course use whichever syntax we decide so maybe we
> need to understand the sorts of jobs users themselves will want to write that
> would make use of system-level events. I wonder if most of these will in fact
> relate to bridged udev events?

That'd be my guess. Some may be reacting to network events too but those
are ultimately processed udev events anyway :)

Most of the other start conditions using :sys: events would be for
system jobs, but for those we'll need to make the bridge a lot more
clever and have all the "started" events re-emitted at the time the
bridge starts. Until then, I don't expect anyone to make much use of that.

> ---
> 
> As an alternative approach, we could introduce a 'match' stanza that would
> ensure that, if specified, non-prefixed events would actually match those events
> whose prefix is specified by the match stanza. For example, the following 2 user
> jobs would be equivalent:
> 
> job1.conf:
>   # reference 2 system-level events explicitly
>   start on :sys:foo and :sys:started bar
> 
> job2.conf:
>   # reference 2 system-level events implicitly
>   match :sys:
>   start on foo and started bar
> 
> 
> Pros and Cons of adding a 'match' stanza:
> 
> + means start/stop on conditions can be identical to system-level
> + less visual 'noise' in complex conditions
> + user jobs can be promoted to system jobs without change (since 'match :sys:'
> would be the default at the system level anyway) [1]
> 
> - introducing a new stanza has an impact on stateful re-exec (new support code
> and tests required).

I don't think it's worth it, adding that stanza means we'll pretty much
force our users to read the cookbook to figure out exactly what's going
on. While it's a good idea for our users to go read our documentation, I
really like the simplicity of most of our jobs, with just a few clear
stanzas that pretty much anyone can understand without having any
upstart knowledge.

> Kind regards,
> 
> James.
> 
> [1] - Note that for minimal 'noise', the match stanza could even live in an
> override file.
> --
> James Hunt
> ____________________________________
> http://upstart.ubuntu.com/cookbook
> http://upstart.ubuntu.com/cookbook/upstart_cookbook.pdf
> 

-- 
Stéphane Graber
Ubuntu developer
http://www.ubuntu.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 901 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/upstart-devel/attachments/20130212/669a8900/attachment.pgp>