Differences between revisions 9 and 10
Revision 9 as of 2007-02-21 18:50:33
Size: 8510
Editor: scott
Comment: failure
Revision 10 as of 2011-08-26 04:10:16
Size: 8510
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 64: Line 64:
 * '''or'''.[[BR]]  * '''or'''.<<BR>>
Line 70: Line 70:
 * '''and'''.[[BR]]  * '''and'''.<<BR>>
Line 76: Line 76:
 * '''until'''.[[BR]]  * '''until'''.<<BR>>
Line 109: Line 109:
 * '''EVENT'''.[[BR]]  * '''EVENT'''.<<BR>>

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

Summary

The current job definition format allows only the simplest of event configuration, a list of OR'd events stating when the job will be started or stopped. This specification proposes a new complex scheme for when that is not sufficient.

Rationale

The simple scheme is useful for tasks, which are often started as a result of either only one or a choice of events. It's also useful enough for simple services that are started and stopped by one other thing. It is not flexible enough to handle the majority of cases that we encounter, this specification fixes that.

Use cases

  • A network-aware daemon needs to be running when there is both a network and filesystem, possibly being stopped and started multiple times.
  • DBUS services need to be running whenever the DBUS daemon is available, and stopped or restarted if that is.

Scope

This specification is limited to the definition and implementation of the new syntax, it relies on the JobsAsState specification to allow this syntax to be split amongst multiple files.

Design

Stanza

This specification introduces a new configuration file stanza that defines a state based on a parsed set of events.

  • The name of this stanza is not yet decided, on will suffice during development, but is not expected to be final.

    on ...
  • The arguments to this stanza are parsed as an infix expression of operators and operands.
    on OPERAND OPERATOR \
       OPERAND OPERATOR (OPERAND OPERATOR OPERAND)
  • Expressions can be grouped with parentheses; within these, newlines are treated as whitespace (Python-esque).
    on OPERAND OPERATOR (OPERAND
                         OPERATOR OPERAND)
  • A grouping expression may only follow an operator, it is a syntax error for one to follow an operand.

Behaviour

  • The complete expression is parsed into a tree, with each node consisting of an operator or operand.
  • Each node has a boolean value initially set to FALSE, the value is changed depending on the type of operator or operand.
  • When the value of a node is changed, that change is propagated upwards with each parent node getting a chance to re-evaluate its value.
  • When the root node of the tree changes, the goal of the job is changed. START when the value is TRUE, STOP when the value is FALSE.
  • If the goal changes by other means, the tree is not reset, however any change to the tree will adjust the goal again.

Operators

  • or.
    The most basic operator, its value is TRUE if the value of either child is TRUE. This acts as a logical or, or period-wise intersection:

    on some-event or some-other-event
  • and.
    The partner to or, its value is TRUE if the value of both children is TRUE. This acts as a logical and, or period-wise union:

    on some-event and some-other-event
  • until.
    This operator defines a period between two expressions. When the value of its left-hand child becomes TRUE, the operator's value is TRUE and the value of the right-hand child and its children is set to FALSE. When the value of its right-hand child becomes TRUE, the operator's value is FALSE and the value of the left-hand child and its children is set to FALSE.

    on some-event until some-other-event

    The behaviour of or and and on this operator is to act as a union or intersection of the two periods respectively.

    on some-event until some-other-event or one-event until another-event
    on some-event until some-other-event and one-event until another-event

    In the first example, the job will be running if either some-event has happened but some-other-event has not, or one-event has happened but another-event has not. In the second example, the job will be running if some-event has happened but some-other-event has not, and one-event has happened but another-event as not.

    Either operand may be a grouped expression, or and and may be used in those and act as before.

    on (some-event or one-event) until (some-other-event or another-event)
    on (some-event and one-event) until (some-other-event and another-event)

    In the first example, the job will be running if either some-event or one-event have happened, and neither some-other-event or another-event have happened. In the second example, the job will be running if both some-event and one-event have happened, but either neither, or only one of, some-other-event and another-event have happened.

    Note the difference between the two combinations, those with multiple until operators explicitly pair events together; where those with grouped expressions do not.

The following precedence is defined:

  • until

  • or, and

Operands

The following operands are defined:

  • EVENT.
    This is the fundamental operand and is expected after the or, and or until operators and as the first operand within a grouped expression. It consists of the name of an event and an optional series of arguments to that event, exactly as if given to start on or stop on.

    on block-device-added hd*

    The value is TRUE once the event has occurred, and is only ever set to FALSE if part of an until expression.

Examples

Combinations of these stanzas can be used to dramatically powerful effect:

  • Job should be running while there is both a network and filesystem. Note that and acts as an intersection in this example.

    on network-up until network-down \
       and filesystem-mounted until filesystem-unmounted
  • Job should be running while any display manager is running. Note that or acts as a union in this example:

    on started gdm until stopping gdm \
       or started kdm until stopping kdm
  • Job should be running with apache, but only if there's a network up.
    on started apache until stopping apache \
       and network-up until network-down

The JobsAsStates specification allows a file in /etc/event.d to contain just a complex event configuration, when combined with the with stanza, this allows custom states to be defined.

  • /etc/event.d/multiuser

    on network-up until network-down \
       and filesystem-mounted until filesystem-unmounted

    /etc/event.d/apache

    on started multiuser until stopping multiuser

It should be noted that the intent of this complex configuration is not to define the causes of a job starting or stopping, but the state of the system during which the job should be running. For this reason, there is no direct equivalent of the stop on EVENT configuration, or complex method of defining a stop state. The until operator is intended for that purpose.

  • start on foo
    start on bar
    
    stop on frodo
    stop on bilbo

is equivalent to

  • on (foo or bar) until (frodo or bilbo)

Implementation

Code

Data preservation and migration

Unresolved issues

  • Name of the stanza; on isn't right.

  • Interaction with GoalChangeEvent and EventCompletion. Currently only the last event would cause the job to change goal, so information about prior events would be lost. Take the following example:

    on block-device-added and some-other-event
    Which block device was added is lost if that is the event that happens first. Unfortunately it's not as simple as referencing multiple event emissions, since that would cause the first event to block, perhaps indefinitely, until or in case the later events happen.
  • Also any event in a complex stanza could never fail.
  • Interaction with instance jobs. Currently since only the last event changes the goal, only the last event causes an instance to be spawned; at which point instances are much easier to be spawned. In addition, since instances don't copy state from their parent, until won't work.


CategorySpec

ComplexEventConfig (last edited 2011-08-26 04:10:16 by localhost)