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
|
/**
* @file callback_job.h
*
* @brief Interface of callback_job_t.
*
*/
/*
* Copyright (C) 2007 Martin Willi
* 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.
*/
#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;
/**
* @brief Job requeueing policy
*
* The job requeueing policy defines how a job is handled when the callback
* function returns.
*
* @ingroup jobs
*/
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,
};
/**
* @brief 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
*
* @ingroup jobs
*/
typedef job_requeue_t (*callback_job_cb_t)(void *data);
/**
* @brief 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
*
* @ingroup jobs
*/
typedef void (*callback_job_cleanup_t)(void *data);
/**
* @brief 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.
*
* @b Constructors:
* - callback_job_create()
*
* @ingroup jobs
*/
struct callback_job_t {
/**
* The job_t interface.
*/
job_t job_interface;
/**
* @brief Cancel the jobs thread and wait for its termination.
*
* @param this calling object
*/
void (*cancel)(callback_job_t *this);
};
/**
* @brief 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
*
* @ingroup jobs
*/
callback_job_t *callback_job_create(callback_job_cb_t cb, void *data,
callback_job_cleanup_t cleanup,
callback_job_t *parent);
#endif /* CALLBACK_JOB_H_ */
|
