updated Doxyfile
[strongswan.git] / src / charon / processing / jobs / callback_job.h
1 /*
2 * Copyright (C) 2007 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 *
15 * $Id$
16 */
17
18 /**
19 * @defgroup callback_job callback_job
20 * @{ @ingroup jobs
21 */
22
23 #ifndef CALLBACK_JOB_H_
24 #define CALLBACK_JOB_H_
25
26 typedef struct callback_job_t callback_job_t;
27
28 #include <library.h>
29 #include <processing/jobs/job.h>
30
31
32 typedef enum job_requeue_t job_requeue_t;
33
34 /**
35 * Job requeueing policy
36 *
37 * The job requeueing policy defines how a job is handled when the callback
38 * function returns.
39 */
40 enum job_requeue_t {
41
42 /**
43 * Do not requeue job, destroy it
44 */
45 JOB_REQUEUE_NONE,
46
47 /**
48 * Reque the job fairly, meaning it has to requeue as any other job
49 */
50 JOB_REQUEUE_FAIR,
51
52 /**
53 * Reexecute the job directly, without the need of requeueing it
54 */
55 JOB_REQUEUE_DIRECT,
56 };
57
58 /**
59 * The callback function to use for the callback job.
60 *
61 * This is the function to use as callback for a callback job. It receives
62 * a parameter supplied to the callback jobs constructor.
63 *
64 * @param data param supplied to job
65 * @return requeing policy how to requeue the job
66 */
67 typedef job_requeue_t (*callback_job_cb_t)(void *data);
68
69 /**
70 * Cleanup function to use for data cleanup.
71 *
72 * The callback has an optional user argument which receives data. However,
73 * this data may be cleaned up if it is allocated. This is the function
74 * to supply to the constructor.
75 *
76 * @param data param supplied to job
77 * @return requeing policy how to requeue the job
78 */
79 typedef void (*callback_job_cleanup_t)(void *data);
80
81 /**
82 * Class representing an callback Job.
83 *
84 * This is a special job which allows a simple callback function to
85 * be executed by a thread of the thread pool. This allows simple execution
86 * of asynchronous methods, without to manage threads.
87 */
88 struct callback_job_t {
89 /**
90 * The job_t interface.
91 */
92 job_t job_interface;
93
94 /**
95 * Cancel the jobs thread and wait for its termination.
96 */
97 void (*cancel)(callback_job_t *this);
98 };
99
100 /**
101 * Creates a callback job.
102 *
103 * The cleanup function is called when the job gets destroyed to destroy
104 * the associated data.
105 * If parent is not NULL, the specified job gets an association. Whenever
106 * the parent gets cancelled (or runs out), all of its children are cancelled,
107 * too.
108 *
109 * @param cb callback to call from the processor
110 * @param data user data to supply to callback
111 * @param cleanup destructor for data on destruction, or NULL
112 * @param parent parent of this job
113 * @return callback_job_t object
114 */
115 callback_job_t *callback_job_create(callback_job_cb_t cb, void *data,
116 callback_job_cleanup_t cleanup,
117 callback_job_t *parent);
118
119 #endif /** CALLBACK_JOB_H_ @}*/