src/core/job.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #pragma once
   4
   5 /***
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 ***/
  23
  24 #include <stdbool.h>
  25 #include <inttypes.h>
  26 #include <errno.h>
  27
  28 typedef struct Job Job;
  29 typedef struct JobDependency JobDependency;
  30 typedef enum JobType JobType;
  31 typedef enum JobState JobState;
  32 typedef enum JobMode JobMode;
  33 typedef enum JobResult JobResult;
  34
  35 /* Be careful when changing the job types! Adjust job_merging_table[] accordingly! */
  36 enum JobType {
  37         JOB_START,                  /* if a unit does not support being started, we'll just wait until it becomes active */
  38         JOB_VERIFY_ACTIVE,
  39
  40         JOB_STOP,
  41
  42         JOB_RELOAD,                 /* if running, reload */
  43
  44         /* Note that restarts are first treated like JOB_STOP, but
  45          * then instead of finishing are patched to become
  46          * JOB_START. */
  47         JOB_RESTART,                /* If running, stop. Then start unconditionally. */
  48
  49         _JOB_TYPE_MAX_MERGING,
  50
  51         /* JOB_NOP can enter into a transaction, but as it won't pull in
  52          * any dependencies, it won't have to merge with anything.
  53          * job_install() avoids the problem of merging JOB_NOP too (it's
  54          * special-cased, only merges with other JOB_NOPs). */
  55         JOB_NOP = _JOB_TYPE_MAX_MERGING, /* do nothing */
  56
  57         _JOB_TYPE_MAX_IN_TRANSACTION,
  58
  59         /* JOB_TRY_RESTART can never appear in a transaction, because
  60          * it always collapses into JOB_RESTART or JOB_NOP before entering.
  61          * Thus we never need to merge it with anything. */
  62         JOB_TRY_RESTART = _JOB_TYPE_MAX_IN_TRANSACTION, /* if running, stop and then start */
  63
  64         /* JOB_RELOAD_OR_START won't enter into a transaction and cannot result
  65          * from transaction merging (there's no way for JOB_RELOAD and
  66          * JOB_START to meet in one transaction). It can result from a merge
  67          * during job installation, but then it will immediately collapse into
  68          * one of the two simpler types. */
  69         JOB_RELOAD_OR_START,        /* if running, reload, otherwise start */
  70
  71         _JOB_TYPE_MAX,
  72         _JOB_TYPE_INVALID = -1
  73 };
  74
  75 enum JobState {
  76         JOB_WAITING,
  77         JOB_RUNNING,
  78         _JOB_STATE_MAX,
  79         _JOB_STATE_INVALID = -1
  80 };
  81
  82 enum JobMode {
  83         JOB_FAIL,                /* Fail if a conflicting job is already queued */
  84         JOB_REPLACE,             /* Replace an existing conflicting job */
  85         JOB_REPLACE_IRREVERSIBLY, /* Like JOB_REPLACE + produce irreversible jobs */
  86         JOB_ISOLATE,             /* Start a unit, and stop all others */
  87         JOB_IGNORE_DEPENDENCIES, /* Ignore both requirement and ordering dependencies */
  88         JOB_IGNORE_REQUIREMENTS, /* Ignore requirement dependencies */
  89         _JOB_MODE_MAX,
  90         _JOB_MODE_INVALID = -1
  91 };
  92
  93 enum JobResult {
  94         JOB_DONE,                /* Job completed successfully */
  95         JOB_CANCELED,            /* Job canceled by a conflicting job installation or by explicit cancel request */
  96         JOB_TIMEOUT,             /* JobTimeout elapsed */
  97         JOB_FAILED,              /* Job failed */
  98         JOB_DEPENDENCY,          /* A required dependency job did not result in JOB_DONE */
  99         JOB_SKIPPED,             /* JOB_RELOAD of inactive unit; negative result of JOB_VERIFY_ACTIVE */
 100         _JOB_RESULT_MAX,
 101         _JOB_RESULT_INVALID = -1
 102 };
 103
 104 #include "sd-event.h"
 105 #include "manager.h"
 106 #include "unit.h"
 107 #include "hashmap.h"
 108 #include "list.h"
 109
 110 struct JobDependency {
 111         /* Encodes that the 'subject' job needs the 'object' job in
 112          * some way. This structure is used only while building a transaction. */
 113         Job *subject;
 114         Job *object;
 115
 116         LIST_FIELDS(JobDependency, subject);
 117         LIST_FIELDS(JobDependency, object);
 118
 119         bool matters;
 120         bool conflicts;
 121 };
 122
 123 struct Job {
 124         Manager *manager;
 125         Unit *unit;
 126
 127         LIST_FIELDS(Job, transaction);
 128         LIST_FIELDS(Job, run_queue);
 129         LIST_FIELDS(Job, dbus_queue);
 130
 131         LIST_HEAD(JobDependency, subject_list);
 132         LIST_HEAD(JobDependency, object_list);
 133
 134         /* Used for graph algs as a "I have been here" marker */
 135         Job* marker;
 136         unsigned generation;
 137
 138         uint32_t id;
 139
 140         JobType type;
 141         JobState state;
 142
 143         sd_event_source *timer_event_source;
 144         usec_t begin_usec;
 145
 146         /* There can be more than one client, because of job merging. */
 147         Set *subscribed;
 148
 149         JobResult result;
 150
 151         bool installed:1;
 152         bool in_run_queue:1;
 153         bool matters_to_anchor:1;
 154         bool override:1;
 155         bool in_dbus_queue:1;
 156         bool sent_dbus_new_signal:1;
 157         bool ignore_order:1;
 158         bool forgot_bus_clients:1;
 159         bool irreversible:1;
 160 };
 161
 162 Job* job_new(Unit *unit, JobType type);
 163 Job* job_new_raw(Unit *unit);
 164 void job_free(Job *job);
 165 Job* job_install(Job *j);
 166 int job_install_deserialized(Job *j);
 167 void job_uninstall(Job *j);
 168 void job_dump(Job *j, FILE*f, const char *prefix);
 169 int job_serialize(Job *j, FILE *f, FDSet *fds);
 170 int job_deserialize(Job *j, FILE *f, FDSet *fds);
 171 int job_coldplug(Job *j);
 172
 173 JobDependency* job_dependency_new(Job *subject, Job *object, bool matters, bool conflicts);
 174 void job_dependency_free(JobDependency *l);
 175
 176 int job_merge(Job *j, Job *other);
 177
 178 JobType job_type_lookup_merge(JobType a, JobType b) _pure_;
 179
 180 _pure_ static inline bool job_type_is_mergeable(JobType a, JobType b) {
 181         return job_type_lookup_merge(a, b) >= 0;
 182 }
 183
 184 _pure_ static inline bool job_type_is_conflicting(JobType a, JobType b) {
 185         return !job_type_is_mergeable(a, b);
 186 }
 187
 188 _pure_ static inline bool job_type_is_superset(JobType a, JobType b) {
 189         /* Checks whether operation a is a "superset" of b in its actions */
 190         return a == job_type_lookup_merge(a, b);
 191 }
 192
 193 bool job_type_is_redundant(JobType a, UnitActiveState b) _pure_;
 194
 195 /* Collapses a state-dependent job type into a simpler type by observing
 196  * the state of the unit which it is going to be applied to. */
 197 void job_type_collapse(JobType *t, Unit *u);
 198
 199 int job_type_merge_and_collapse(JobType *a, JobType b, Unit *u);
 200
 201 void job_add_to_run_queue(Job *j);
 202 void job_add_to_dbus_queue(Job *j);
 203
 204 int job_start_timer(Job *j);
 205
 206 int job_run_and_invalidate(Job *j);
 207 int job_finish_and_invalidate(Job *j, JobResult result, bool recursive);
 208
 209 char *job_dbus_path(Job *j);
 210
 211 void job_shutdown_magic(Job *j);
 212
 213 const char* job_type_to_string(JobType t) _const_;
 214 JobType job_type_from_string(const char *s) _pure_;
 215
 216 const char* job_state_to_string(JobState t) _const_;
 217 JobState job_state_from_string(const char *s) _pure_;
 218
 219 const char* job_mode_to_string(JobMode t) _const_;
 220 JobMode job_mode_from_string(const char *s) _pure_;
 221
 222 const char* job_result_to_string(JobResult t) _const_;
 223 JobResult job_result_from_string(const char *s) _pure_;