Differences between revisions 6 and 7
Revision 6 as of 2006-12-13 19:25:14
Size: 4595
Editor: scott
Comment: document callbacks and subscription
Revision 7 as of 2011-08-26 04:10:17
Size: 4595
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

Once events reach the top of the queue, they are passed to the jobs and forgotten about. There is no way to determine when the effect of an event has finished. This specification proposes keeping a record of events currently in the process of being handled, and tracking when the handling has finished.

Rationale

Being able to track the completion of events is useful for user interface reasons, as well as allowing us to serialise events or determine their failure.

Use cases

  • initctl emit should not return until the event has been handled, and in the mean time should show the effect it has.

  • We currently issue a shutdown event such as reboot once the system is idle after a shutdown event, it would be much cleaner (and less error-prone) to issue it once the shutdown event finished.

  • It would be useful for startup, as we could then issue a series of events one after the other.
  • We wish to perform job serialisation, so that dbus is not stopped until all sub-services are stopped first.

Scope

This specification extends the changes defined in GoalChangeEvent to allow tracking of that event, and determining when it has completed. Further uses are defined by other specifications.

Design

  • When an event is taken off the queue and emitted, it will be put into a new list of events currently in the process of being handled. It's this new structure that will be referred to from the job.
  • Any job will release its hold on the event once it reaches the JOB_STOPPED state.

  • A job with service or respawn specified (a service) will also release its hold on the event once it reaches the JOB_RUNNING state.

  • If a job fails (as defined by the JobFailedEvent specification), the event will also be marked as failed.

  • When an event has been handled, if it was marked as failed, an event will be issued.
    • This event will be named for the event that failed, with /failed appended to the name.

      on startup/failed
    • The arguments and environment will be identical to the failing event.
      on network-interface-up/failed eth0
    • Events ending in /failed do not issue a /failed event if they fail.

Implementation

Code

A new EventEmission structure will be defined in init/event.h as follows:

  • typedef struct event_emission {
        Event          *event;
    
        int             jobs;
        int             failed;
    
        EventEmittedCb  callback;
        void           *data;
    } EventEmission;

These point to the Event structure, and use that structure's list entry to store themselves in a list. Both the queue and handling lists will use this structure, yet retaining polymorphism for events as well.

The jobs member indicates the number of jobs that have not yet completed, once this reaches zero, the emission structure is automatically removed and freed.

Before the structure is freed, the callback function will be run, passing the emission structure and the user data. This function is specified when the event is queued, and can be used to perform a next step now that the event has completed.

The goal_event member of the Job structure is changed to be:

  • EventEmission *goal_event;

During job_change_state in init/job.c, if we reach the appropriate state for the job, we call a new event_finished function. This function decrements the jobs member, and returns to indicate whether the emission has completed or not. Either way, we clear the goal_event member.

The failed member is set by job_child_reaper in init/job.c if it emits the failed event.

event_emission_finished will emit the /failed event if the event was so marked.

Subscription code in init/control.c will be extended so that a subscription can be added for a particular event emission; any changes occurring due to this event will be notified to the subscriber, and the subscription cleared by the callback function.

Data preservation and migration

These changes are backwards compatible with the previous behaviour.


CategorySpec

EventCompletion (last edited 2011-08-26 04:10:17 by localhost)