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.
Launchpad entry: https://launchpad.net/products/upstart/+spec/goal-change-event
When a job's goal is changed by an event, no information about that event is currently stored in the job, so there's no way to communicate information from the event to the job. This specification proposes changing that so that the event that starts or stops a job is recorded.
Several different desired behaviours are only possible if the job has some record of the event that changed its goal. This is useful both to allow the job to react differently based on the event received, obtain information from the event rather than racey tools or simply to determine when the effect of an event has been completed.
We would like to know when all effects of the startup or shutdown events have been completed, rather than waiting for the system to enter an idle or stalled state.
- If we know whether an event has completed, we can also have the notion of whether an event has failed to be handled properly.
The initctl emit command should be able to output a list of what the command caused, likewise for other library users.
- Jobs should be able to react differently based on the event received, so we need some way of knowing which event information to pass.
We desire to include arguments and environment in the event (see EventStructure), this can also only happen if we know which event information to pass.
The scope of this specification is limited to adding support for recording the goal change event. Uses of this will be specified elsewhere.
When the goal of a job is changed by an event, we will record this event in the job so that it may be used for other purposes.
The Job structure defined in init/job.h will gain an additional member:
This will be initially set to NULL. Note that the name and type of this member is subject to change by future specifications such as EventCompletion.
The job_start and job_stop functions will be moved to static functions that perform the actual work. Functions with those names will continue to exist, but will set the goal_event member to NULL to indicate that the job goal was changed manually.
The job_start_event and job_stop_event functions will call the static functions after setting the goal_event member to a copy of the event received; assuming it matches, of course.
In all cases, any existing goal event should be freed.
Data preservation and migration
These changes are backwards compatible with the previous behaviour.