9516c4ebde488a5fd3f082cdfffcfeaf9b57f9d2
[strongswan.git] / Source / charon / job_queue.h
1 /**
2 * @file job_queue.h
3 *
4 * @brief Job-Queue based on linked_list_t
5 *
6 */
7
8 /*
9 * Copyright (C) 2005 Jan Hutter, 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 JOB_QUEUE_H_
24 #define JOB_QUEUE_H_
25
26 #include "linked_list.h"
27
28 /**
29 * Type of Jobs in Job-Queue
30 */
31 typedef enum job_type_e job_type_t;
32
33 enum job_type_e{
34 /**
35 * process an incoming IKEv2-Message
36 */
37 INCOMING_PACKET,
38 /**
39 * retransmit an IKEv2-Message
40 */
41 RETRANSMIT_REQUEST,
42 /**
43 * establish an ike sa as initiator
44 */
45 ESTABLISH_IKE_SA
46 /* more job types have to be inserted here */
47 };
48
49
50 /**
51 * @brief Job as it is stored in the job queue
52 *
53 * A job consists of a job-type and an assigned value
54 *
55 * The value-type for a specific job is not discussed here
56 */
57 typedef struct job_s job_t;
58
59 struct job_s{
60 /**
61 * Type of job
62 */
63 job_type_t type;
64 /**
65 * Every job has its assigned_data based on the job type
66 */
67 void * assigned_data;
68
69 /**
70 * @brief Destroys a job_t object
71 *
72 * @param job_t calling object
73 * @returns SUCCESS if succeeded, FAILED otherwise
74 */
75 status_t (*destroy) (job_t *job);
76 };
77
78 /**
79 * @brief Creates a job of specific type
80 *
81 * @param type type of the job
82 * @param assigned_data value to assign to the job
83 *
84 * @return job_t job object
85 */
86 job_t *job_create(job_type_t type, void *assigned_data);
87
88 /**
89 * @brief Job-Queue
90 *
91 * Despite the job-queue is based on a linked_list_t
92 * all access functions are thread-save implemented
93 */
94 typedef struct job_queue_s job_queue_t;
95
96 struct job_queue_s {
97
98 /**
99 * @brief returns number of jobs in queue
100 *
101 * @param job_queue_t calling object
102 * @param[out] count integer pointer to store the job count in
103 * @returns SUCCESS if succeeded, FAILED otherwise
104 */
105 status_t (*get_count) (job_queue_t *job_queue, int *count);
106
107 /**
108 * @brief get the next job from the queue
109 *
110 * If the queue is empty, this function blocks until a job can be returned.
111 *
112 * After using, the returned job has to get destroyed by the caller.
113 *
114 * @param job_queue_t calling object
115 * @param[out] job pointer to a job pointer where to job is returned to
116 * @returns SUCCESS if succeeded, FAILED otherwise
117 */
118 status_t (*get) (job_queue_t *job_queue, job_t **job);
119
120 /**
121 * @brief adds a job to the queue
122 *
123 * This function is non blocking and adds a job_t to the list.
124 * The specific job-object has to get destroyed by the thread which
125 * removes the job.
126 *
127 * @param job_queue_t calling object
128 * @param[in] job job to add to the queue (job is not copied)
129 * @returns SUCCESS if succeeded, FAILED otherwise
130 */
131 status_t (*add) (job_queue_t *job_queue, job_t *job);
132
133 /**
134 * @brief destroys a job_queue object
135 *
136 * @warning The caller of this function has to make sure
137 * that no thread is going to add or get a job from the job_queue
138 * after calling this function.
139 *
140 * @param job_queue_t calling object
141 * @returns SUCCESS if succeeded, FAILED otherwise
142 */
143 status_t (*destroy) (job_queue_t *job_queue);
144 };
145
146 /**
147 * @brief Creates an empty job_queue
148 *
149 * @return job_queue_t empty job_queue
150 */
151 job_queue_t *job_queue_create();
152 #endif /*JOB_QUEUE_H_*/