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