4:59 p.m.
This is my initial definition of a new internal job control api. I am
working on this as a part of the google summer of code. These patches
contain the core job control api and deal only with managing individual
jobs. I am currently working on writing code using this api to manage
jobs in domains, in such a way that I will be able to replace the
current job control code in qemu and libxl. Ultimately I will use this
to implement job control in the storage driver which is my ultimate
goal for the summer of code.
---
src/Makefile.am | 1 +
src/util/virjobcontrol.c | 574 +++++++++++++++++++++++++++++++++++++++++++++++
src/util/virjobcontrol.h | 342 ++++++++++++++++++++++++++++
3 files changed, 917 insertions(+)
create mode 100644 src/util/virjobcontrol.c
create mode 100644 src/util/virjobcontrol.h
diff --git a/src/Makefile.am b/src/Makefile.am
index 2b9ac61..77de0e7 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -118,6 +118,7 @@ UTIL_SOURCES = \
util/virinitctl.c util/virinitctl.h \
util/viriptables.c util/viriptables.h \
util/viriscsi.c util/viriscsi.h \
+ util/virjobcontrol.h util/virjobcontrol.c \
util/virjson.c util/virjson.h \
util/virkeycode.c util/virkeycode.h \
util/virkeyfile.c util/virkeyfile.h \
diff --git a/src/util/virjobcontrol.c b/src/util/virjobcontrol.c
new file mode 100644
index 0000000..04a5246
--- /dev/null
+++ b/src/util/virjobcontrol.c
@@ -0,0 +1,574 @@
+/*
+ * virjobcontrol.c Core implementation of job control
+ *
+ * Copyright (C) 2014 Tucker DiNapoli
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ *
+ * Author: Tucker DiNapoli
+ */
+
+#include <config.h>
+
+#include "virjobcontrol.h"
+#include "viralloc.h"
+#include "virtime.h"
+#include "virlog.h"
+VIR_LOG_INIT("virjobcontrol");
+
+VIR_ENUM_IMPL(virJob, 4,
+ "none",
+ "query",
+ "modify",
+ "destroy",
+);
+/*
+ No files other then this and virjobcontrol.c should need to
+ have access to the core implmentation of jobs. The code in these
+ files is intended to serve as a base for job control independent of
+ drivers.
+*/
+
+#define LOCK_JOB(job) \
+ virMutexLock(&job->lock)
+#define UNLOCK_JOB(job) \
+ virMutexUnlock(&job->lock)
+#define LOCK_JOB_INFO(job) \
+ virMutexLock(&job->info->lock)
+#define UNLOCK_JOB_INFO(job) \
+ virMutexUnlock(&job->info->lock)
+#define GET_CURRENT_TIME(time) \
+ if (virTimeMillisNow(&time) < 0) { \
+ return -1; \
+ }
+
+
+#define CHECK_FLAG_ATOMIC(job, flag) (virAtomicIntGet(&job->flags) &
VIR_JOB_FLAG_##flag)
+#define CHECK_FLAG(job, flag) (job->flags & VIR_JOB_FLAG_##flag)
+#define SET_FLAG_ATOMIC(job, flag) (virAtomicIntOr(&job->flags,
VIR_JOB_FLAG_##flag))
+#define SET_FLAG(job, flag) (job->flags |= VIR_JOB_FLAG_##flag)
+#define UNSET_FLAG_ATOMIC(job, flag) (virAtomicIntAnd(&job->flags,
(~VIR_JOB_FLAG_##flag)))
+#define UNSET_FLAG(job, flag) (job->flags &= (~VIR_JOB_FLAG_##flag))
+#define CLEAR_FLAGS_ATOMIC(job) (virAtomicIntSet(&job->flags, VIR_JOB_FLAG_NONE))
+#define CLEAR_FLAGS(job) (job->flags = VIR_JOB_FLAG_NONE)
+
+typedef struct _jobHashEntry {
+ virJobID id;
+ virJobObjPtr job;
+ struct _jobHashEntry *next;
+} jobHashEntry;
+
+typedef struct _jobHash {
+ jobHashEntry **table;
+ size_t size;
+ size_t num_entries;
+ virRWLock lock;
+} jobHash;
+
+/* Using this incures a cost on every call to a job control function
+ that uses the job control hash table, but it means that no one using
+ job control needs to call an initialization function to use it.
+
+ The other option would be to have a function:
+ virJobControlInit(void)
+ {
+ return virOnce(job_once, jobControlInit);
+ }
+ and require anyone using job control to call it.
+ */
+static struct _jobHash *job_hash; /* Hash table that contians all current jobs */
+static int init_err = 0;
+static virOnceControl job_once = VIR_ONCE_CONTROL_INITIALIZER;
+static void
+jobControlInit(void)
+{
+ if (VIR_ALLOC_QUIET(job_hash) < 0) {
+ init_err = 1;
+ }
+ if (virRWLockInit(&job_hash->lock) < 0) {
+ init_err = 1;
+ }
+ if (VIR_ALLOC_N_QUIET(job_hash->table, 16) <0) {
+ init_err = 1;
+ }
+}
+
+/* global job id
+
+ Because it gets incremented before it's first use 0 is
+ never a valid job id
+
+ Only ever touched with atomic instructions.
+*/
+static unsigned int global_id = 0;
+
+
+
+/* Simple hash table implementation for jobs.
+ It is keyed by job id's which are just integers so there isn't acutally
+ a hash function. Using the existing hash table in libvirt would be overkill.
+*/
+
+#ifndef VIR_JOB_REHASH_THRESHOLD
+#define VIR_JOB_REHASH_THRESHOLD 0.8
+#endif
+
+#ifndef VIR_JOB_BUCKET_LEN
+#define VIR_JOB_BUCKET_LEN 5
+#endif
+
+#ifndef VIR_JOB_GROWTH_FACTOR
+#define VIR_JOB_GROWTH_FACTOR 2
+#endif
+
+#define READ_LOCK_TABLE(ht) virRWLockRead((virRWLockPtr)&ht->lock)
+#define WRITE_LOCK_TABLE(ht) virRWLockWrite((virRWLockPtr)&ht->lock)
+#define UNLOCK_TABLE(ht) virRWLockUnlock((virRWLockPtr)&ht->lock)
+
+static int jobHashRehash(jobHash *ht);
+#define maybe_rehash(ht) \
+ if (((double)ht->size*VIR_JOB_BUCKET_LEN)/(ht->num_entries) >= \
+ VIR_JOB_REHASH_THRESHOLD){ \
+ jobHashRehash(ht); \
+ }
+
+
+/* Doesn't lock ht, so should only be called with a write lock held on ht*/
+static int jobHashRehash(jobHash *ht);
+
+/* look for id in the hash table ht and return the entry associated with it
+ if id isn't it the table return null*/
+static jobHashEntry*
+jobLookup(const jobHash *ht, virJobID id)
+{
+ if (virOnce(&job_once, jobControlInit) < 0) {
+ return NULL;
+ }
+ READ_LOCK_TABLE(ht);
+ int bucket = id % ht->size;
+ jobHashEntry *retval = NULL, *job_entry;
+ if (!ht->table[bucket]) {
+ goto end;
+ }
+ job_entry = ht->table[bucket];
+ do {
+ if (job_entry->id == id) {
+ retval = job_entry;
+ goto end;
+ }
+ } while ((job_entry = job_entry->next));
+
+ end:
+ UNLOCK_TABLE(ht);
+ return retval;
+}
+
+/* add job the hashtable of currently existing jobs, job should
+ have already been initialized via virJobObjInit.
+ returns 0 if job is already in the hash,
+ returns the id of the job if it was successfully added
+ returns -1 on error.
+ */
+static int
+jobHashAdd(jobHash *ht, virJobObjPtr job)
+{
+ if (virOnce(&job_once, jobControlInit) < 0) {
+ return -1;
+ }
+ virJobID id = job->id;
+ if (jobLookup(ht, id)) { /* check if job is in the table*/
+ return 0;
+ }
+ int bucket = id % ht->size;
+ jobHashEntry *new_entry;
+ if (VIR_ALLOC_QUIET(new_entry) < 0) {
+ return -1;
+ }
+ jobHashEntry *last_entry = ht->table[bucket];
+ *new_entry = (jobHashEntry) {.id = id, .job = job};
+
+ WRITE_LOCK_TABLE(ht);
+ if (!last_entry) {
+ ht->table[bucket] = new_entry;
+ } else {
+ while (last_entry->next) {
+ last_entry = last_entry->next;
+ }
+ last_entry->next = new_entry;
+ }
+ ht->num_entries++;
+ maybe_rehash(ht);
+ UNLOCK_TABLE(ht);
+ return id;
+}
+
+/* Remove the job with the given id from the list of currently existing jobs,
+ this doesn't free/cleanup the actual job object, it just removes
+ the hash entry, this is called by virJobObjFree, so there shouldn't
+ be any reason to call it directly.
+
+ return values are the same as for jobAlist add, 0 if no job found,
+ job id on success, -1 on some other error;
+*/
+static int
+jobHashRemove(jobHash *ht, virJobID id)
+{
+ int bucket = id % ht->size;
+ /*we can't just call jobLookup because we need the entry before the one
+ we want to free*/
+ WRITE_LOCK_TABLE(ht);
+ jobHashEntry *entry = ht->table[bucket], *old_entry;
+ if (!entry) {
+ goto error;
+ }
+ if (entry->id != id) {
+ while (entry && entry->next->id != id) {
+ entry = entry->next;
+ }
+ }
+ if (!entry) {
+ goto error;
+ }
+ old_entry = entry->next;
+ entry->next = old_entry->next;
+ VIR_FREE(old_entry);
+ UNLOCK_TABLE(ht);
+ return id;
+ error:
+ UNLOCK_TABLE(ht);
+ return 0;
+}
+static int
+jobHashRehash(jobHash *ht)
+{
+ size_t new_size = ht->size*VIR_JOB_GROWTH_FACTOR;
+ jobHashEntry **new_table;
+ if (VIR_ALLOC_N_QUIET(new_table, new_size)) {
+ return -1;
+ }
+ jobHashEntry **old_table = ht->table;
+ int index;
+ for (index = 0; index<ht->size; index++) {
+ jobHashEntry *old_entry = old_table[index];
+ while (old_entry) {
+ int bucket = old_entry->id % new_size;
+ jobHashEntry *new_entry = new_table[bucket];
+ if (!new_entry) {
+ new_table[bucket] = old_entry;
+ } else {
+ while (new_entry->next) {
+ new_entry = new_entry->next;
+ }
+ new_entry->next = old_entry;
+ }
+ old_entry = old_entry->next;
+ }
+ }
+ ht->size = new_size;
+ ht->table = new_table;
+ VIR_FREE(old_table);
+ return 1;
+}
+
+#define jobIDFromJobInternal(job) (job->id)
+
+static inline virJobObjPtr
+jobFromIDInternal(virJobID id)
+{
+ jobHashEntry *entry = jobLookup(job_hash, id);
+ if (entry) {
+ return entry->job;
+ } else {
+ return NULL;
+ }
+}
+
+virJobObjPtr
+virJobFromID(virJobID id)
+{
+ return jobFromIDInternal(id);
+
+}
+virJobID
+virJobIDFromJob(virJobObjPtr job)
+{
+ return jobIDFromJobInternal(job);
+}
+
+int
+virJobObjInit(virJobObjPtr job)
+{
+ /* This code checks to see if job was already initialized,
+ I don't know if this is needed or not.*/
+ if (job->id != 0) {
+ VIR_DEBUG("job %d has already been initialized", job->id);
+ return 0;
+ }
+ job->id = virAtomicIntInc(&global_id);
+ job->maxJobsWaiting = INT_MAX;
+
+ if (virCondInit(&job->cond) < 0) {
+ return -1;
+ }
+
+ if (virMutexInit(&job->lock) < 0) {
+ virCondDestroy(&job->cond);
+ return -1;
+ }
+
+ jobHashAdd(job_hash, job);
+
+ return job->id;
+}
+
+void
+virJobObjFree(virJobObjPtr job)
+{
+ virCondDestroy(&job->cond);
+ jobHashRemove(job_hash, job->id);
+ VIR_FREE(job);
+}
+
+void
+virJobObjCleanup(virJobObjPtr job)
+{
+
+ virCondDestroy(&job->cond);
+ jobHashRemove(job_hash, job->id);
+ memset(job, '\0', sizeof(virJobObj));
+ return;
+}
+
+int
+virJobObjBegin(virJobObjPtr job,
+ virJobType type)
+{
+ LOCK_JOB(job);
+ if (CHECK_FLAG(job, ACTIVE)) {
+ VIR_DEBUG("Job %d is already running", job->id);
+ UNLOCK_JOB(job);
+ return 0;
+ }
+ VIR_DEBUG("Starting job %d with type %s",
+ job->id, virJobTypeToString(type));
+ unsigned long long now;
+ if (job->id <= 0) {
+ goto error; /* job wasn't initialiazed*/
+ }
+ if (virTimeMillisNow(&now) < 0) {
+ goto error;
+ }
+ job->type = type;
+ SET_FLAG(job, ACTIVE);
+ job->start = now;
+ job->owner = virThreadSelfID();
+ return job->id;
+ error:
+ UNLOCK_JOB(job);
+ return -1;
+}
+
+int
+virJobObjEnd(virJobObjPtr job)
+{
+ if (job->type == VIR_JOB_NONE) {
+ return -1;
+ }
+ virJobObjReset(job);
+ virCondSignal(&job->cond);
+
+ return job->id;
+}
+
+/* There shouldn't be any threads waiting on job when this is called*/
+int
+virJobObjReset(virJobObjPtr job)
+{
+ LOCK_JOB(job);
+ job->type = VIR_JOB_NONE;
+ job->flags = VIR_JOB_FLAG_NONE;
+ job->owner = 0;
+ job->jobsWaiting = 0;
+ UNLOCK_JOB(job);
+
+ return job->id;
+}
+
+int
+virJobObjAbort(virJobObjPtr job)
+{
+ int retval;
+ LOCK_JOB(job);
+ if (CHECK_FLAG(job, ACTIVE) || CHECK_FLAG(job, SUSPENDED)) {
+ SET_FLAG(job, ABORTED);
+ retval = job->id;
+ } else {
+ retval = -1;
+ }
+ UNLOCK_JOB(job);
+ return retval;
+}
+
+int
+virJobObjAbortAndSignal(virJobObjPtr job)
+{
+ int retval;
+ LOCK_JOB(job);
+ if (CHECK_FLAG(job, ACTIVE) || CHECK_FLAG(job, SUSPENDED)) {
+ SET_FLAG(job, ABORTED);
+ retval = job->id;
+ virCondBroadcast(&job->cond);
+ } else {
+ retval = -1;
+ }
+ UNLOCK_JOB(job);
+ return retval;
+}
+
+/* lock should be held by the calling function*/
+int
+virJobObjWait(virJobObjPtr job,
+ virMutexPtr lock,
+ unsigned long long limit)
+{
+
+ bool job_lock = false;
+ int retval;
+ if (CHECK_FLAG_ATOMIC(job, ACTIVE)) { /* if the job isn't active we're
fine*/
+ if (virAtomicIntInc(&job->jobsWaiting) > job->maxJobsWaiting) {
+ errno = 0;
+ goto error;
+ }
+ if (!lock) {
+ LOCK_JOB(job);
+ lock = &job->lock;
+ job_lock = true;
+ }
+ while (CHECK_FLAG_ATOMIC(job, ACTIVE)) {
+ if (limit) {
+ retval = virCondWaitUntil(&job->cond, lock, limit);
+ } else {
+ retval = virCondWait(&job->cond, lock);
+ }
+ if (retval < 0) {
+ goto error;
+ }
+ }
+ }
+ virAtomicIntDec(&job->jobsWaiting);
+ if (job_lock) {
+ UNLOCK_JOB(job);
+ }
+ return job->id;
+
+ error:
+ virAtomicIntDec(&job->jobsWaiting);
+ if (job_lock) {
+ UNLOCK_JOB(job);
+ }
+ if (!errno) {
+ return -3;
+ } else if (errno == ETIMEDOUT) {
+ return -2;
+ } else {
+ return -1;
+ }
+}
+
+int
+virJobObjSuspend(virJobObjPtr job)
+{
+ if (!CHECK_FLAG_ATOMIC(job, ACTIVE)) {
+ return -1;
+ }
+ LOCK_JOB(job);
+ SET_FLAG(job, SUSPENDED);
+ UNSET_FLAG(job, ACTIVE);
+ UNLOCK_JOB(job);
+ return job->id;
+}
+int
+virJobObjResume(virJobObjPtr job)
+{
+ if (!CHECK_FLAG_ATOMIC(job, SUSPENDED)) {
+ return -1;
+ }
+ LOCK_JOB(job);
+ UNSET_FLAG(job, SUSPENDED);
+ SET_FLAG(job, ACTIVE);
+ UNLOCK_JOB(job);
+ return job->id;
+}
+int
+virJobObjResumeIfNotAborted(virJobObjPtr job)
+{
+ int retval;
+ LOCK_JOB(job);
+ if (!CHECK_FLAG(job, SUSPENDED)) {
+ retval = -1;
+ } else if (CHECK_FLAG(job, ABORTED)) {
+ retval = 0;
+ } else {
+ UNSET_FLAG(job, SUSPENDED);
+ SET_FLAG(job, ACTIVE);
+ retval = job->id;
+ }
+ UNLOCK_JOB(job);
+ return retval;
+}
+
+void
+virJobObjSetMaxWaiters(virJobObjPtr job, int max)
+{
+ virAtomicIntSet(&job->maxJobsWaiting, max);
+}
+
+bool
+virJobObjCheckAbort(virJobObjPtr job)
+{
+ return CHECK_FLAG_ATOMIC(job, ABORTED);
+}
+bool
+virJobObjActive(virJobObjPtr job)
+{
+ return CHECK_FLAG_ATOMIC(job, ACTIVE);
+}
+
+/* since we need to be able to return a negitive answer on error
+ the time difference we can return is only half of the maximum
+ possible time. This shouldn't pose any real issue.
+*/
+long long
+virJobObjCheckTime(virJobObjPtr job)
+{
+ if (!CHECK_FLAG(job, ACTIVE)) {
+ return 0;
+ }
+ unsigned long long now;
+ if (virTimeMillisNow(&now) < 0) {
+ return -1;
+ }
+ return now - job->start;
+}
+
+void
+virJobObjSignal(virJobObjPtr job, bool all)
+{
+ if (all) {
+ virCondBroadcast(&job->cond);
+ } else {
+ virCondSignal(&job->cond);
+ }
+}
diff --git a/src/util/virjobcontrol.h b/src/util/virjobcontrol.h
new file mode 100644
index 0000000..235cc06
--- /dev/null
+++ b/src/util/virjobcontrol.h
@@ -0,0 +1,342 @@
+/*
+ * virjobcontrol.h Core implementation of job control
+ *
+ * Copyright (C) 2014 Tucker DiNapoli
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ *
+ * Author: Tucker DiNapoli
+ */
+
+
+#ifndef __JOB_CONTROL_H__
+#define __JOB_CONTROL_H__
+
+#include <stdlib.h>
+
+#include "viratomic.h"
+#include "virthread.h"
+#include "virutil.h"
+
+
+/* The general type of the job, specifically if it will modify
+ the object it is acting on.*/
+typedef enum {
+ VIR_JOB_NONE = 0, /*no job running*/
+ VIR_JOB_QUERY = 0x1, /* job will not change object state (read-only)*/
+ VIR_JOB_MODIFY = 0x2, /* job may change object state (read-write)*/
+ VIR_JOB_DESTROY = 0x4, /* job will destroy the object it is acting on */
+ VIR_JOB_LAST
+} virJobType;
+VIR_ENUM_DECL(virJob);
+
+
+/* General metadata/flags for jobs
+
+ more specific flags can be added for speciic drivers,
+ to do this the first value of the enum for the extra flags
+ should be set to (VIR_JOB_FLAG_LAST << 1) and each additional
+ flag should be set to the last flag shifted to the left by 1.
+
+*/
+typedef enum {
+ VIR_JOB_FLAG_NONE = 0x000, /* No job is active */
+ VIR_JOB_FLAG_ACTIVE = 0x001, /* Job is active */
+ /* These next flags are used to indicate how progress should be measured
+ and are currently unused
+ */
+ VIR_JOB_FLAG_TIME_BOUND = 0x002, /* Job is bound by a specific ammount of time */
+ VIR_JOB_FLAG_MEM_BOUND = 0x004, /* Job is bound by a specific ammount of memory
*/
+ VIR_JOB_FLAG_FILE_BOUND = 0x008, /* Job is bound by a specific number of files */
+ VIR_JOB_FLAG_DATA_BOUND = 0x010, /* Job is bound by a specific ammount of data */
+ VIR_JOB_FLAG_UNBOUNDED = 0x020, /* Job has no specific bound */
+ /* These flags indicate a job is no longer active but still exists
+ */
+ VIR_JOB_FLAG_SUSPENDED = 0x040, /* Job is Suspended and can be resumed */
+ VIR_JOB_FLAG_COMPLETED = 0x080, /* Job has finished, but isn't cleaned up */
+ VIR_JOB_FLAG_FAILED = 0x100, /* Job hit error, but isn't cleaned up */
+ VIR_JOB_FLAG_ABORTED = 0x200, /* Job was aborted, but isn't cleaned up */
+ VIR_JOB_FLAG_LAST = 0x400
+} virJobFlag;
+
+
+typedef int virJobID; /*signed so negitive values can be returned on error*/
+typedef struct _virJobObj virJobObj;
+typedef virJobObj *virJobObjPtr;
+typedef struct _virJobInfo virJobInfo;
+typedef virJobInfo *virJobInfoPtr;
+
+struct _virJobObj {
+ /* this should only be locked when changing the job object, not while running a job
+ it's use is mostly optional, but it is needed for waiting on a job*/
+ virMutex lock;/*should have a compile time option to enable/disable locking */
+ virCond cond; /* Use to coordinate jobs (is this necessary?) */
+ virJobType type; /* The type of the job */
+ unsigned long long owner; /* Thread id which set current job */
+ unsigned long long start; /* when the job started*/
+ int jobsWaiting; /* number jobs waiting on cond */
+ int maxJobsWaiting; /* max number of jobs that can wait on cond */
+ /* information about the job, this is a private struct, access to information
+ about the job should be obtained by functions */
+ virJobInfoPtr info;
+ virJobID id; /* the job id, constant, and unique */
+ virJobFlag flags; /* The current state of the job */
+ void *privateData;
+};
+
+/* Getting information on a currently running job is currently unimplmeneted and
+ any suggestions on what should go into the api for querying/setting job
+ progress information would be appreciated
+*/
+typedef enum {
+ VIR_JOB_INFO_NONE = 0,
+ VIR_JOB_INFO_TIME,
+ VIR_JOB_INFO_MEM,
+ VIR_JOB_INFO_FILE,
+ VIR_JOB_INFO_DATA,
+ VIR_JOB_INFO_LAST
+} virJobInfoType;
+
+struct _virJobInfo {
+ /* these fields are for compatability with existing job
+ information structs.
+ */
+ virDomainBlockJobInfoPtr blockJobInfoPtr;
+ virDomainJobInfoPtr domainJobInfoPtr;
+
+ unsigned long long progressTotal;
+ unsigned long long dataTotal;
+ unsigned long long memTotal;
+ unsigned long long filesTotal;
+ unsigned long long timeTotal;
+
+ unsigned long long progressProcessed;
+ unsigned long long timeProcessed;
+ unsigned long long memProcessed;
+ unsigned long long filesProcessed;
+ unsigned long long dataProcessed;
+
+ unsigned long long progressRemaining;
+ unsigned long long dataRemaining;
+ unsigned long long memRemaining;
+ unsigned long long filesRemaining;
+ unsigned long long timeRemaining;
+};
+
+/**
+ * virJobObjInit:
+ * @job: Pointer to the job object to initialize
+ *
+ * Initialize the job object given, should be called before any other
+ * job function.
+ *
+ * Like all job functions it returns the job id on success and -1 on error
+ */
+int virJobObjInit(virJobObjPtr job);
+/**
+ * virJobObjFree:
+ * @job: Pointer to the job object to free
+ *
+ * Cleanup/free all resources/memory assoicated with job
+ */
+void virJobObjFree(virJobObjPtr job);
+/**
+ * virJobObjCleanup:
+ * @job: Pointer to the job object to cleanup
+ *
+ * Cleanup all resources assoicated with job, and zero out the
+ * corrsponding memory, but do not free it.
+ */
+
+void virJobObjCleanup(virJobObjPtr job);
+/**
+ * virJobObjBegin:
+ * @job: The job to begin
+ * @type: The type of job that is being started
+ *
+ * Marks job as active, sets the calling thread as the owner of the job,
+ * sets the job's start time to the current time and sets it's type to type.
+ *
+ * End job should be called after this, once the job is done
+ *
+ * Returns the job id of job on success, 0 if job is already active
+ * and -1 on error.
+ */
+int virJobObjBegin(virJobObjPtr job,
+ virJobType type);
+/**
+ * virJobObjEnd:
+ *
+ * @job: The job to end
+ *
+ * Ends job, calls virJobObjReset and signals all threads waiting on job.
+ *
+ * Ending a job does not invalidate the job object, and a new job can be
+ * started using the same job object, call virJobObjFree or virJobObjCleanup
+ * in order to destroy a job object.
+ *
+ * returns the job's id on success and -1 if the job was not active.
+ */
+int virJobObjEnd(virJobObjPtr job);
+/**
+ * virJobObjReset:
+ *
+ * @job: The job to reset
+ *
+ * Clears all fields of job related to running a job. This does not
+ * clear the job id, any configurable parameters (currently just the
+ * maximum number of waiting threads), or the mutex/condition variable
+ * assoicated with the job. This is called internally by virJobObjEnd
+ * and there should be few reasons to call this explicitly.
+ */
+int virJobObjReset(virJobObjPtr job);
+/**
+ * virJobObjAbort:
+ * @job: The job to abort
+ *
+ * Marks job as aborted, since jobs are asyncronous this doesn't actually
+ * stop the job. The abort status of a job can be checked by
+ * virJobObjCheckAbort. A suspended job can be aborted.
+ *
+ * returns the job id on success and -1 if
+ * job is not currently running/suspended.
+ */
+int virJobObjAbort(virJobObjPtr job);
+/**
+ * virJobObjAbort:
+ * @job: The job to abort/signal waiters
+ *
+ * Behaves identically to virJobObjAbort except all threads waiting
+ * on job are signaled after the abort status is set.
+ */
+int virJobObjAbortAndSignal(virJobObjPtr job);
+/**
+ * virJobObjSuspend:
+ * @job: The job to suspend
+ *
+ * Marks job as suspended, it is up to the caller of the function
+ * to actually save any state assoicated with the job
+ *
+ * This function returns the job's id on success and -1 if the job
+ * was not active.
+ */
+int virJobObjSuspend(virJobObjPtr job);
+/**
+ * virJobObjResume:
+ * @job The job to resume
+ *
+ * Resume job, as with virJobObjSuspend it is up to the caller to
+ * insure that the work being done by job is actually restarted.
+ *
+ * Since a job can be aborted while it is suspended the caller should
+ * check to see if job has been aborted, a convenience function
+ * virJobObjResumeIfNotAborted is provided.
+ *
+ * returns the job id if job was resumed and -1 if the job was not suspended.
+ */
+int virJobObjResume(virJobObjPtr job);
+
+/**
+ * virJobObjResumeIfNotAborted:
+ * @job The job to resume
+ *
+ * Behaves the same as virJobObjResume except it returns 0 and does not
+ * resume the job if the job was aborted while suspended.
+ */
+int virJobObjResumeIfNotAborted(virJobObjPtr job);
+
+/* returns -3 if max waiters is exceeded, -2 on timeout, -1 on other error*/
+/**
+ * virJobObjWait:
+ * @job: The job to wait on
+ * @lock: The lock to use in the call to virCondWait
+ * @limit: If not 0 the maximum ammount of time to wait (in milliseconds)
+ *
+ * This function waits for job to be completed, or to otherwise signal on it's
+ * condition variable.
+ *
+ * If lock is NULL the internal job lock will be used, otherwise lock should
+ * be held by the calling thread.
+ * (NOTE: I'm not sure if it's a good idea or not to use the internal lock)
+ *
+ * If limit is > 0 virCondWaitUntil is called instead of virCondWait with limit
+ * being used as the time parameter.
+ *
+ * If job is not currently active return successfully.
+ *
+ * Like all job functions returns the job's id on success.
+ *
+ * On Failure returns a negitive number to indicate the cause of failure
+ * -3 indicates the maximum number of threads were alread waiting on job
+ * -2 indicates that virCondWaitUntil timed out
+ * -1 indicates some other error in virCondWait/virCondWaitUntil
+ */
+int virJobObjWait(virJobObjPtr job,
+ virMutexPtr lock,
+ unsigned long long limit);
+/* Should I provide a function to wait for a suspended job to resume? */
+
+/**
+ * virJobObjSignal:
+ * @job: The job to signal from
+ * @all: If true signal all waiting threads, otherwise just signal one
+ *
+ * Signal a thread/threads waiting on job. In most cases waiting threads
+ * are signaled when needed internally, but this is provided if for
+ * some reason waiting threads need to be manually signaled.
+ */
+
+void virJobObjSignal(virJobObjPtr job, bool all);
+
+/* accessor functions*/
+/**
+ * virJobObjCheckAbort:
+ * @job: The job whoes status should be checked
+ *
+ * Returns true if job has been aborted, false otherwise
+ */
+bool virJobObjCheckAbort(virJobObjPtr job);
+/**
+ * virJobObjCheckTime:
+ * @job: The job whoes time should be checked
+ *
+ * Returns the time in milliseconds that job has been running for.
+ * returns 0 if job is not active and -1 if there is an error in
+ * getting the current time.
+ */
+long long virJobObjCheckTime(virJobObjPtr job);
+/**
+ * virJobObjActive:
+ * @job: The job whoes status should be checked
+ *
+ * Returns true if job is currently active, false otherwise
+ */
+bool virJobObjActive(virJobObjPtr job);
+/**
+ * virJobObjSetMaxWaiters:
+ * @job: The job to modify
+ * @max: The maximum number of threads to allow to wait on job at once
+ *
+ * Sets the maximum number of threads that can simultaneously wait on job.
+ * By default there is essentially no limit (in reality the limit is the
+ * maximum value that can be held by an int)
+ */
+void virJobObjSetMaxWaiters(virJobObjPtr job, int max);
+
+/* These convert between a job object and a job id.
+*/
+virJobObjPtr virJobFromID(virJobID id);
+virJobID virJobIDFromJob(virJobObjPtr job);
+#endif
--
2.0.0