1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
/*
* Copyright (C) 2007-2011 Martin Willi
* Copyright (C) 2011 revosec AG
* 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;
/**
* 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);
/**
* Creates a callback job, with priority.
*
* Same as callback_job_create(), but with different priorities than default.
*
* @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
* @param prio job priority
* @return callback_job_t object
*/
callback_job_t *callback_job_create_with_prio(callback_job_cb_t cb, void *data,
callback_job_cleanup_t cleanup, callback_job_t *parent,
job_priority_t prio);
#endif /** CALLBACK_JOB_H_ @}*/
|
