Removed strayed code fragment
[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
16 /**
17 * @defgroup callback_job callback_job
18 * @{ @ingroup jobs
19 */
20
21 #ifndef CALLBACK_JOB_H_
22 #define CALLBACK_JOB_H_
23
24 typedef struct callback_job_t callback_job_t;
25
26 #include <library.h>
27 #include <processing/jobs/job.h>
28
29
30 typedef enum job_requeue_t job_requeue_t;
31
32 /**
33 * Job requeueing policy
34 *
35 * The job requeueing policy defines how a job is handled when the callback
36 * function returns.
37 */
38 enum job_requeue_t {
39
40 /**
41 * Do not requeue job, destroy it
42 */
43 JOB_REQUEUE_NONE,
44
45 /**
46 * Reque the job fairly, meaning it has to requeue as any other job
47 */
48 JOB_REQUEUE_FAIR,
49
50 /**
51 * Reexecute the job directly, without the need of requeueing it
52 */
53 JOB_REQUEUE_DIRECT,
54 };
55
56 /**
57 * The callback function to use for the callback job.
58 *
59 * This is the function to use as callback for a callback job. It receives
60 * a parameter supplied to the callback jobs constructor.
61 *
62 * @param data param supplied to job
63 * @return requeing policy how to requeue the job
64 */
65 typedef job_requeue_t (*callback_job_cb_t)(void *data);
66
67 /**
68 * Cleanup function to use for data cleanup.
69 *
70 * The callback has an optional user argument which receives data. However,
71 * this data may be cleaned up if it is allocated. This is the function
72 * to supply to the constructor.
73 *
74 * @param data param supplied to job
75 * @return requeing policy how to requeue the job
76 */
77 typedef void (*callback_job_cleanup_t)(void *data);
78
79 /**
80 * Class representing an callback Job.
81 *
82 * This is a special job which allows a simple callback function to
83 * be executed by a thread of the thread pool. This allows simple execution
84 * of asynchronous methods, without to manage threads.
85 */
86 struct callback_job_t {
87 /**
88 * The job_t interface.
89 */
90 job_t job_interface;
91
92 /**
93 * Cancel the job's thread and wait for its termination. This only works
94 * reliably for jobs that always use JOB_REQUEUE_FAIR or JOB_REQUEUE_DIRECT,
95 * otherwise the job may already be destroyed when cancel is called. */
96 void (*cancel)(callback_job_t *this);
97 };
98
99 /**
100 * Creates a callback job.
101 *
102 * The cleanup function is called when the job gets destroyed to destroy
103 * the associated data.
104 * If parent is not NULL, the specified job gets an association. Whenever
105 * the parent gets cancelled (or runs out), all of its children are cancelled,
106 * too.
107 *
108 * @param cb callback to call from the processor
109 * @param data user data to supply to callback
110 * @param cleanup destructor for data on destruction, or NULL
111 * @param parent parent of this job
112 * @return callback_job_t object
113 */
114 callback_job_t *callback_job_create(callback_job_cb_t cb, void *data,
115 callback_job_cleanup_t cleanup,
116 callback_job_t *parent);
117
118 #endif /** CALLBACK_JOB_H_ @}*/