Moving charon to libcharon.

src/libcharon/processing/jobs/callback_job.h

@@ -0,0 +1,118 @@
+/*
+ * Copyright (C) 2007 Martin Willi
+ * Hochschule fuer Technik Rapperswil
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
+ *
+ * This program 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 General Public License
+ * for more details.
+ */
+
+/**
+ * @defgroup callback_job callback_job
+ * @{ @ingroup jobs
+ */
+
+#ifndef CALLBACK_JOB_H_
+#define CALLBACK_JOB_H_
+
+typedef struct callback_job_t callback_job_t;
+
+#include <library.h>
+#include <processing/jobs/job.h>
+
+
+typedef enum job_requeue_t job_requeue_t;
+
+/**
+ * Job requeueing policy
+ *
+ * The job requeueing policy defines how a job is handled when the callback
+ * function returns.
+ */
+enum job_requeue_t {
+
+	/**
+	 * Do not requeue job, destroy it
+	 */
+	JOB_REQUEUE_NONE,
+
+	/**
+	 * Reque the job fairly, meaning it has to requeue as any other job
+	 */
+	JOB_REQUEUE_FAIR,
+
+	/**
+	 * Reexecute the job directly, without the need of requeueing it
+	 */
+	JOB_REQUEUE_DIRECT,
+};
+
+/**
+ * The callback function to use for the callback job.
+ *
+ * This is the function to use as callback for a callback job. It receives
+ * a parameter supplied to the callback jobs constructor.
+ *
+ * @param data			param supplied to job
+ * @return				requeing policy how to requeue the job
+ */
+typedef job_requeue_t (*callback_job_cb_t)(void *data);
+
+/**
+ * Cleanup function to use for data cleanup.
+ *
+ * The callback has an optional user argument which receives data. However,
+ * this data may be cleaned up if it is allocated. This is the function
+ * to supply to the constructor.
+ *
+ * @param data			param supplied to job
+ * @return				requeing policy how to requeue the job
+ */
+typedef void (*callback_job_cleanup_t)(void *data);
+
+/**
+ * Class representing an callback Job.
+ *
+ * This is a special job which allows a simple callback function to
+ * be executed by a thread of the thread pool. This allows simple execution
+ * of asynchronous methods, without to manage threads.
+ */
+struct callback_job_t {
+	/**
+	 * The job_t interface.
+	 */
+	job_t job_interface;
+
+	/**
+	 * Cancel the job's thread and wait for its termination. This only works
+	 * reliably for jobs that always use JOB_REQUEUE_FAIR or JOB_REQUEUE_DIRECT,
+	 * otherwise the job may already be destroyed when cancel is called. */
+	void (*cancel)(callback_job_t *this);
+};
+
+/**
+ * Creates a callback job.
+ *
+ * The cleanup function is called when the job gets destroyed to destroy
+ * the associated data.
+ * If parent is not NULL, the specified job gets an association. Whenever
+ * the parent gets cancelled (or runs out), all of its children are cancelled,
+ * too.
+ *
+ * @param cb				callback to call from the processor
+ * @param data				user data to supply to callback
+ * @param cleanup			destructor for data on destruction, or NULL
+ * @param parent			parent of this job
+ * @return					callback_job_t object
+ */
+callback_job_t *callback_job_create(callback_job_cb_t cb, void *data,
+									callback_job_cleanup_t cleanup,
+									callback_job_t *parent);
+
+#endif /** CALLBACK_JOB_H_ @}*/