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
  26 #include "sd-event.h"
  27
  28 #include "list.h"
  29
  30 typedef struct Job Job;
  31 typedef struct JobDependency JobDependency;
  32 typedef enum JobType JobType;
  33 typedef enum JobState JobState;
  34 typedef enum JobMode JobMode;
  35 typedef enum JobResult JobResult;
  36
  37 /* Be careful when changing the job types! Adjust job_merging_table[] accordingly! */
  38 enum JobType {
  39         JOB_START,                  /* if a unit does not support being started, we'll just wait until it becomes active */
  40         JOB_VERIFY_ACTIVE,
  41
  42         JOB_STOP,
  43
  44         JOB_RELOAD,                 /* if running, reload */
  45
  46         /* Note that restarts are first treated like JOB_STOP, but
  47          * then instead of finishing are patched to become
  48          * JOB_START. */
  49         JOB_RESTART,                /* If running, stop. Then start unconditionally. */
  50
  51         _JOB_TYPE_MAX_MERGING,
  52
  53         /* JOB_NOP can enter into a transaction, but as it won't pull in
  54          * any dependencies and it uses the special 'nop_job' slot in Unit,
  55          * it won't have to merge with anything (except possibly into another
  56          * JOB_NOP, previously installed). JOB_NOP is special-cased in
  57          * job_type_is_*() functions so that the transaction can be
  58          * activated. */
  59         JOB_NOP = _JOB_TYPE_MAX_MERGING, /* do nothing */
  60
  61         _JOB_TYPE_MAX_IN_TRANSACTION,
  62
  63         /* JOB_TRY_RESTART can never appear in a transaction, because
  64          * it always collapses into JOB_RESTART or JOB_NOP before entering.
  65          * Thus we never need to merge it with anything. */
  66         JOB_TRY_RESTART = _JOB_TYPE_MAX_IN_TRANSACTION, /* if running, stop and then start */
  67
  68         /* JOB_RELOAD_OR_START won't enter into a transaction and cannot result
  69          * from transaction merging (there's no way for JOB_RELOAD and
  70          * JOB_START to meet in one transaction). It can result from a merge
  71          * during job installation, but then it will immediately collapse into
  72          * one of the two simpler types. */
  73         JOB_RELOAD_OR_START,        /* if running, reload, otherwise start */
  74
  75         _JOB_TYPE_MAX,
  76         _JOB_TYPE_INVALID = -1
  77 };
  78
  79 enum JobState {
  80         JOB_WAITING,
  81         JOB_RUNNING,
  82         _JOB_STATE_MAX,
  83         _JOB_STATE_INVALID = -1
  84 };
  85
  86 enum JobMode {
  87         JOB_FAIL,                /* Fail if a conflicting job is already queued */
  88         JOB_REPLACE,             /* Replace an existing conflicting job */
  89         JOB_REPLACE_IRREVERSIBLY,/* Like JOB_REPLACE + produce irreversible jobs */
  90         JOB_ISOLATE,             /* Start a unit, and stop all others */
  91         JOB_FLUSH,               /* Flush out all other queued jobs when queing this one */
  92         JOB_IGNORE_DEPENDENCIES, /* Ignore both requirement and ordering dependencies */
  93         JOB_IGNORE_REQUIREMENTS, /* Ignore requirement dependencies */
  94         _JOB_MODE_MAX,
  95         _JOB_MODE_INVALID = -1
  96 };
  97
  98 enum JobResult {
  99         JOB_DONE,                /* Job completed successfully */
 100         JOB_CANCELED,            /* Job canceled by a conflicting job installation or by explicit cancel request */
 101         JOB_TIMEOUT,             /* Job timeout elapsed */
 102         JOB_FAILED,              /* Job failed */
 103         JOB_DEPENDENCY,          /* A required dependency job did not result in JOB_DONE */
 104         JOB_SKIPPED,             /* Negative result of JOB_VERIFY_ACTIVE */
 105         JOB_INVALID,             /* JOB_RELOAD of inactive unit */
 106         JOB_ASSERT,              /* Couldn't start a unit, because an assert didn't hold */
 107         JOB_UNSUPPORTED,         /* Couldn't start a unit, because the unit type is not supported on the system */
 108         _JOB_RESULT_MAX,
 109         _JOB_RESULT_INVALID = -1
 110 };
 111
 112 #include "unit.h"
 113
 114 struct JobDependency {
 115         /* Encodes that the 'subject' job needs the 'object' job in
 116          * some way. This structure is used only while building a transaction. */
 117         Job *subject;
 118         Job *object;
 119
 120         LIST_FIELDS(JobDependency, subject);
 121         LIST_FIELDS(JobDependency, object);
 122
 123         bool matters;
 124         bool conflicts;
 125 };
 126
 127 struct Job {
 128         Manager *manager;
 129         Unit *unit;
 130
 131         LIST_FIELDS(Job, transaction);
 132         LIST_FIELDS(Job, run_queue);
 133         LIST_FIELDS(Job, dbus_queue);
 134
 135         LIST_HEAD(JobDependency, subject_list);
 136         LIST_HEAD(JobDependency, object_list);
 137
 138         /* Used for graph algs as a "I have been here" marker */
 139         Job* marker;
 140         unsigned generation;
 141
 142         uint32_t id;
 143
 144         JobType type;
 145         JobState state;
 146
 147         sd_event_source *timer_event_source;
 148         usec_t begin_usec;
 149
 150         /*
 151          * This tracks where to send signals, and also which clients
 152          * are allowed to call DBus methods on the job (other than
 153          * root).
 154          *
 155          * There can be more than one client, because of job merging.
 156          */
 157         sd_bus_track *clients;
 158         char **deserialized_clients;
 159
 160         JobResult result;
 161
 162         bool installed:1;
 163         bool in_run_queue:1;
 164         bool matters_to_anchor:1;
 165         bool override:1;
 166         bool in_dbus_queue:1;
 167         bool sent_dbus_new_signal:1;
 168         bool ignore_order:1;
 169         bool irreversible:1;
 170 };
 171
 172 Job* job_new(Unit *unit, JobType type);
 173 Job* job_new_raw(Unit *unit);
 174 void job_free(Job *job);
 175 Job* job_install(Job *j);
 176 int job_install_deserialized(Job *j);
 177 void job_uninstall(Job *j);
 178 void job_dump(Job *j, FILE*f, const char *prefix);
 179 int job_serialize(Job *j, FILE *f, FDSet *fds);
 180 int job_deserialize(Job *j, FILE *f, FDSet *fds);
 181 int job_coldplug(Job *j);
 182
 183 JobDependency* job_dependency_new(Job *subject, Job *object, bool matters, bool conflicts);
 184 void job_dependency_free(JobDependency *l);
 185
 186 int job_merge(Job *j, Job *other);
 187
 188 JobType job_type_lookup_merge(JobType a, JobType b) _pure_;
 189
 190 _pure_ static inline bool job_type_is_mergeable(JobType a, JobType b) {
 191         return job_type_lookup_merge(a, b) >= 0;
 192 }
 193
 194 _pure_ static inline bool job_type_is_conflicting(JobType a, JobType b) {
 195         return a != JOB_NOP && b != JOB_NOP && !job_type_is_mergeable(a, b);
 196 }
 197
 198 _pure_ static inline bool job_type_is_superset(JobType a, JobType b) {
 199         /* Checks whether operation a is a "superset" of b in its actions */
 200         if (b == JOB_NOP)
 201                 return true;
 202         if (a == JOB_NOP)
 203                 return false;
 204         return a == job_type_lookup_merge(a, b);
 205 }
 206
 207 bool job_type_is_redundant(JobType a, UnitActiveState b) _pure_;
 208
 209 /* Collapses a state-dependent job type into a simpler type by observing
 210  * the state of the unit which it is going to be applied to. */
 211 JobType job_type_collapse(JobType t, Unit *u);
 212
 213 int job_type_merge_and_collapse(JobType *a, JobType b, Unit *u);
 214
 215 void job_add_to_run_queue(Job *j);
 216 void job_add_to_dbus_queue(Job *j);
 217
 218 int job_start_timer(Job *j);
 219
 220 int job_run_and_invalidate(Job *j);
 221 int job_finish_and_invalidate(Job *j, JobResult result, bool recursive);
 222
 223 char *job_dbus_path(Job *j);
 224
 225 void job_shutdown_magic(Job *j);
 226
 227 const char* job_type_to_string(JobType t) _const_;
 228 JobType job_type_from_string(const char *s) _pure_;
 229
 230 const char* job_state_to_string(JobState t) _const_;
 231 JobState job_state_from_string(const char *s) _pure_;
 232
 233 const char* job_mode_to_string(JobMode t) _const_;
 234 JobMode job_mode_from_string(const char *s) _pure_;
 235
 236 const char* job_result_to_string(JobResult t) _const_;
 237 JobResult job_result_from_string(const char *s) _pure_;
 238
 239 int job_get_timeout(Job *j, uint64_t *timeout) _pure_;