Differences between revisions 5 and 6
Revision 5 as of 2008-03-03 01:59:14
Size: 5123
Editor: scott
Comment:
Revision 6 as of 2011-08-26 04:10:16
Size: 5123
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

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 basic operations on a job of start and stop are already atomic in the sense that they can be repeated in any order, and only the last one issued has any effect. This specification proposes extending their atomicity so that their side-effects such as environment they provide to a job are also atomic based around the commands.

Rationale

Atomicity is one of the keystones to reliable and predictable operation. If none of the side-effects of all possible operations of Upstart are unexpected then users will be inherently more trusting of it. Further specifications such as ExpandEventVariables rely on a predictable environment for a job, which is provided by the start command. That environment needs to be set for all processes of the job, including stop processes, even if the job has been restarted with a different environment in the meantime.

Use cases

  • The apache job may be started with an HTTPS environment variable that specifies whether or not to enable SSL support. Extra handling is required in both the pre-start and post-stop scripts depending on this variable so the value of this variable must always match, whether or not a queued restart intends to change it.

  • The mysql job has a complex set of conditions that can cause it to be automatically stopped. It has a pre-stop script that examines the stop events, and may chose to leave the job running.

  • User scripts will call start or stop and expect them to block until the job either reaches the intended goal state or their command is interrupted by another.

Scope

This scope of this specification is limited to matters of atomicity and side-effects of the start and stop requests, which while including the introduction of a "job environment" does not extend to using that environment.

Design

  • The start and stop requests are considered to be either manual requests through exposed commands or automatic requests through the matching of the event expression; behaviours should be identical.
  • Start requests will be ignored if the job already has a goal of start.
  • Once a start event operator has been matched, it is immediately reset and the entire expression must match again for it to start a job again.
  • Start requests may specifiy environment variables that form part of the job's environment until it is stopped again.
  • Those environment variables are added to the built-ins and those from the job configuration.
  • A further start request will not overwrite those environment variables, instead it will queue its own which will be used once the job reaches the starting state again.
  • Only one queued environment is permitted at one time, further queues will remove that queued. ie. given:
    start foo FOO=bar BAR=baz
    start foo FOO=baz BAR=baz
    start foo FOO=quux

    the foo job will be started with FOO=quux and no set BAR variable.

  • A manual start command on a job identified by id may chose to specify no environment, in which case it will restart the existing job keeping the previous environment.
  • The start request (command or events) will block from issue until one of the following things happens, in which case the request will unblock immediately:
    • The job reaches the running state if a service
    • The job reaches the waiting state
    • A job command fails
    • A new start or stop request is recevied
  • Stop requests will be ignored if the goal of the job is already stop.
  • Once a stop event operator has been matched, it is immediately reset and the entire expression must match again for it to stop the job again.
  • The stop operator is not reset if the job is restarted.
  • Stop requests may also specifiy environment variables, however these are only appended to the job's environment (from the start request) for the pre-stop script. This is because that script can make a decision to restart the job again, and may wish to make an informed decision based on the reason for it stopping.

  • A further stop request (after an intermediate start request) will overwrite those environment variables; in practice this is not important since this request cannot arrive until after the pre-stop script has finished.

  • The stop request (command or events) will block from issue until one of the following things happens, in which case the request will unblock immediately:
    • The job reaches the waiting state
    • A job command fails
    • A new start or stop request is recevied

Implementation

Data preservation and migration

These changes alter the blocking behaviour of the start and stop commands when interrupted by another command; the previous semantics were never documented, so nobody should be relying on them yet.


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