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