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