5450cb61bd717585f093dbc346743af3f7379d96
[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 enum job_requeue_t {
38
39 /**
40 * Do not requeue job, destroy it
41 */
42 JOB_REQUEUE_NONE,
43
44 /**
45 * Reque the job farly, meaning it has to queue as any other job
46 */
47 JOB_REQUEUE_FAIR,
48
49 /**
50 * Reexecute the job directly, without the need of requeing it
51 */
52 JOB_REQUEUE_DIRECT,
53 };
54
55 /**
56 * @brief The callback function to use for the callback job.
57 *
58 * This is the function to use as callback for a callback job. It receives
59 * a parameter supplied to the callback jobs constructor.
60 *
61 * @param data param supplied to job
62 * @return requeing policy how to requeue the job
63 */
64 typedef job_requeue_t (*callback_job_cb_t)(void *data);
65
66 /**
67 * @brief Cleanup function to use for data cleanup.
68 *
69 * The callback has an optional user argument which receives data. However,
70 * this data may be cleaned up if it is allocated. This is the function
71 * to supply to the constructor.
72 *
73 * @param data param supplied to job
74 * @return requeing policy how to requeue the job
75 */
76 typedef void (*callback_job_cleanup_t)(void *data);
77
78 /**
79 * @brief Class representing an callback Job.
80 *
81 * This is a special job which allows a simple callback function to
82 * be executed by a thread of the thread pool. This allows simple execution
83 * of asynchronous methods, without to manage threads.
84 *
85 * @b Constructors:
86 * - callback_job_create()
87 *
88 * @ingroup jobs
89 */
90 struct callback_job_t {
91 /**
92 * The job_t interface.
93 */
94 job_t job_interface;
95
96 /**
97 * @brief Cancel the jobs thread and wait for its termination.
98 *
99 * @param this calling object
100 */
101 void (*cancel)(callback_job_t *this);
102 };
103
104 /**
105 * @brief Creates a callback job.
106 *
107 * The cleanup function is called when the job gets destroyed to destroy
108 * the associated data.
109 * If parent is not NULL, the specified job gets an association. Whenever
110 * the parent gets cancelled (or runs out), all of its children are cancelled,
111 * too.
112 *
113 * @param cb callback to call from the processor
114 * @param data user data to supply to callback
115 * @param cleanup destructor for data on destruction, or NULL
116 * @param parent parent of this job
117 * @return callback_job_t object
118 *
119 * @ingroup jobs
120 */
121 callback_job_t *callback_job_create(callback_job_cb_t cb, void *data,
122 callback_job_cleanup_t cleanup,
123 callback_job_t *parent);
124
125 #endif /* CALLBACK_JOB_H_ */
126