src/core/job.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #ifndef foojobhfoo
   4 #define foojobhfoo
   5
   6 /***
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 ***/
  24
  25 #include <stdbool.h>
  26 #include <inttypes.h>
  27 #include <errno.h>
  28
  29 typedef struct Job Job;
  30 typedef struct JobDependency JobDependency;
  31 typedef struct JobBusClient JobBusClient;
  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, it won't have to merge with anything.
  55          * job_install() avoids the problem of merging JOB_NOP too (it's
  56          * special-cased, only merges with other JOB_NOPs). */
  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_ISOLATE,             /* Start a unit, and stop all others */
  88         JOB_IGNORE_DEPENDENCIES, /* Ignore both requirement and ordering dependencies */
  89         JOB_IGNORE_REQUIREMENTS, /* Ignore requirement dependencies */
  90         _JOB_MODE_MAX,
  91         _JOB_MODE_INVALID = -1
  92 };
  93
  94 enum JobResult {
  95         JOB_DONE,
  96         JOB_CANCELED,
  97         JOB_TIMEOUT,
  98         JOB_FAILED,
  99         JOB_DEPENDENCY,
 100         JOB_SKIPPED,
 101         _JOB_RESULT_MAX,
 102         _JOB_RESULT_INVALID = -1
 103 };
 104
 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 JobBusClient {
 124         LIST_FIELDS(JobBusClient, client);
 125         /* Note that this bus object is not ref counted here. */
 126         DBusConnection *bus;
 127         char name[0];
 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
 138         LIST_HEAD(JobDependency, subject_list);
 139         LIST_HEAD(JobDependency, object_list);
 140
 141         /* Used for graph algs as a "I have been here" marker */
 142         Job* marker;
 143         unsigned generation;
 144
 145         uint32_t id;
 146
 147         JobType type;
 148         JobState state;
 149
 150         Watch timer_watch;
 151
 152         /* There can be more than one client, because of job merging. */
 153         LIST_HEAD(JobBusClient, bus_client_list);
 154
 155         JobResult result;
 156
 157         bool installed:1;
 158         bool in_run_queue:1;
 159         bool matters_to_anchor:1;
 160         bool override:1;
 161         bool in_dbus_queue:1;
 162         bool sent_dbus_new_signal:1;
 163         bool ignore_order:1;
 164         bool forgot_bus_clients:1;
 165 };
 166
 167 JobBusClient* job_bus_client_new(DBusConnection *connection, const char *name);
 168
 169 Job* job_new(Unit *unit, JobType type);
 170 Job* job_new_raw(Unit *unit);
 171 void job_free(Job *job);
 172 Job* job_install(Job *j);
 173 int job_install_deserialized(Job *j);
 174 void job_uninstall(Job *j);
 175 void job_dump(Job *j, FILE*f, const char *prefix);
 176 int job_serialize(Job *j, FILE *f, FDSet *fds);
 177 int job_deserialize(Job *j, FILE *f, FDSet *fds);
 178 int job_coldplug(Job *j);
 179
 180 JobDependency* job_dependency_new(Job *subject, Job *object, bool matters, bool conflicts);
 181 void job_dependency_free(JobDependency *l);
 182
 183 int job_merge(Job *j, Job *other);
 184
 185 JobType job_type_lookup_merge(JobType a, JobType b);
 186
 187 static inline bool job_type_is_mergeable(JobType a, JobType b) {
 188         return job_type_lookup_merge(a, b) >= 0;
 189 }
 190
 191 static inline bool job_type_is_conflicting(JobType a, JobType b) {
 192         return !job_type_is_mergeable(a, b);
 193 }
 194
 195 static inline bool job_type_is_superset(JobType a, JobType b) {
 196         /* Checks whether operation a is a "superset" of b in its actions */
 197         return a == job_type_lookup_merge(a, b);
 198 }
 199
 200 bool job_type_is_redundant(JobType a, UnitActiveState b);
 201
 202 /* Collapses a state-dependent job type into a simpler type by observing
 203  * the state of the unit which it is going to be applied to. */
 204 void job_type_collapse(JobType *t, Unit *u);
 205
 206 int job_type_merge_and_collapse(JobType *a, JobType b, Unit *u);
 207
 208 bool job_is_runnable(Job *j);
 209
 210 void job_add_to_run_queue(Job *j);
 211 void job_add_to_dbus_queue(Job *j);
 212
 213 int job_start_timer(Job *j);
 214 void job_timer_event(Job *j, uint64_t n_elapsed, Watch *w);
 215
 216 int job_run_and_invalidate(Job *j);
 217 int job_finish_and_invalidate(Job *j, JobResult result, bool recursive);
 218
 219 char *job_dbus_path(Job *j);
 220
 221 const char* job_type_to_string(JobType t);
 222 JobType job_type_from_string(const char *s);
 223
 224 const char* job_state_to_string(JobState t);
 225 JobState job_state_from_string(const char *s);
 226
 227 const char* job_mode_to_string(JobMode t);
 228 JobMode job_mode_from_string(const char *s);
 229
 230 const char* job_result_to_string(JobResult t);
 231 JobResult job_result_from_string(const char *s);
 232
 233 #endif