From bf61c583fc04b7fcfeeccec9be0044c85daac796 Mon Sep 17 00:00:00 2001 From: Emanuele Giuseppe Esposito Date: Mon, 26 Sep 2022 05:31:59 -0400 Subject: job: move and update comments from blockjob.c This comment applies more on job, it was left in blockjob as in the past the whole job logic was implemented there. Note: at this stage, job_{lock/unlock} and job lock guard macros are *nop*. No functional change intended. Signed-off-by: Emanuele Giuseppe Esposito Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Stefan Hajnoczi Message-Id: <20220926093214.506243-7-eesposit@redhat.com> Reviewed-by: Kevin Wolf Signed-off-by: Kevin Wolf --- job.c | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'job.c') diff --git a/job.c b/job.c index 87564979cb..926e385ac2 100644 --- a/job.c +++ b/job.c @@ -32,6 +32,22 @@ #include "trace/trace-root.h" #include "qapi/qapi-events-job.h" +/* + * The job API is composed of two categories of functions. + * + * The first includes functions used by the monitor. The monitor is + * peculiar in that it accesses the job list with job_get, and + * therefore needs consistency across job_get and the actual operation + * (e.g. job_user_cancel). To achieve this consistency, the caller + * calls job_lock/job_unlock itself around the whole operation. + * + * + * The second includes functions used by the job drivers and sometimes + * by the core block layer. These delegate the locking to the callee instead. + * + * TODO Actually make this true + */ + /* * job_mutex protects the jobs list, but also makes the * struct job fields thread-safe. -- cgit 1.4.1