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