src/core/job.h

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