1tevent_thread(3) tevent tevent_thread(3)
2
6 tevent_thread - Chapter 6: Tevent with threads
7
10 In order to use tevent with threads, you must first understand how to
11 use the talloc library in threaded programs. For more information about
12 working with talloc, please visit talloc website where tutorial and
13 documentation are located.
14 If a tevent context structure is talloced from a NULL, thread-safe
16 talloc context, then it can be safe to use in a threaded program. The
17 function talloc_disable_null_tracking() must be called from the initial
18 program thread before any talloc calls are made to ensure talloc is
19 thread-safe.
20 Each thread must create it's own tevent context structure as follows
22 tevent_context_init(NULL) and no talloc memory contexts can be shared
23 between threads.
24 Separate threads using tevent in this way can communicate by writing
26 data into file descriptors that are being monitored by a tevent context
27 on another thread. For example (simplified with no error handling):
28 Main thread:
30 main()
32 {
33 talloc_disable_null_tracking();
34 struct tevent_context *master_ev = tevent_context_init(NULL);
36 void *mem_ctx = talloc_new(master_ev);
37 // Create file descriptor to monitor.
39 int pipefds[2];
40 pipe(pipefds);
42 struct tevent_fd *fde = tevent_add_fd(master_ev,
44 mem_ctx,
45 pipefds[0], // read side of pipe
46 TEVENT_FD_READ,
47 pipe_read_handler, // callback function
48 private_data_pointer);
49 // Create sub thread, pass pipefds[1] write side of pipe to it.
51 // The above code not shown here..
52 // Process events.
54 tevent_loop_wait(master_ev);
55 // Cleanup if loop exits.
57 talloc_free(master_ev);
58 }
59 When the subthread writes to pipefds[1], the function
61 pipe_read_handler() will be called in the main thread.
62 sophisticated use
64 A popular way to use an event library within threaded programs is to
65 allow a sub-thread to asynchronously schedule a tevent_immediate
66 function call from the event loop of another thread. This can be built
67 out of the basic functions and isolation mechanisms of tevent, but
68 tevent also comes with some utility functions that make this easier, so
69 long as you understand the limitations that using threads with talloc
70 and tevent impose.
71 To allow a tevent context to receive an asynchronous tevent_immediate
73 function callback from another thread, create a struct
74 tevent_thread_proxy * by calling
75 struct tevent_thread_proxy *tevent_thread_proxy_create(
77 struct tevent_context *dest_ev_ctx);
78 This function allocates the internal data structures to allow
81 asynchronous callbacks as a talloc child of the struct tevent_context
82 *, and returns a struct tevent_thread_proxy * that can be passed to
83 another thread.
84 When you have finished receiving asynchronous callbacks, simply
86 talloc_free the struct tevent_thread_proxy *, or talloc_free the struct
87 tevent_context *, which will deallocate the resources used.
88 To schedule an asynchronous tevent_immediate function call from one
90 thread on the tevent loop of another thread, use
91 void tevent_thread_proxy_schedule(struct tevent_thread_proxy *tp,
93 struct tevent_immediate **pp_im,
94 tevent_immediate_handler_t handler,
95 void **pp_private_data);
96 This function causes the function handler() to be invoked as a
99 tevent_immediate callback from the event loop of the thread that
100 created the struct tevent_thread_proxy * (so the owning struct
101 tevent_context * should be long-lived and not in the process of being
102 torn down).
103 The struct tevent_thread_proxy object being used here is a child of the
105 event context of the target thread. So external synchronization
106 mechanisms must be used to ensure that the target object is still in
107 use at the time of the tevent_thread_proxy_schedule() call. In the
108 example below, the request/response nature of the communication ensures
109 this.
110 The struct tevent_immediate **pp_im passed into this function should be
112 a struct tevent_immediate * allocated on a talloc context local to this
113 thread, and will be reparented via talloc_move to be owned by struct
114 tevent_thread_proxy *tp. *pp_im will be set to NULL on successful
115 scheduling of the tevent_immediate call.
116 handler() will be called as a normal tevent_immediate callback from the
118 struct tevent_context * of the destination event loop that created the
119 struct tevent_thread_proxy *
120 Returning from this functions does not mean that the handler has been
122 invoked, merely that it has been scheduled to be called in the
123 destination event loop.
124 Because the calling thread does not wait for the callback to be
126 scheduled and run on the destination thread, this is a fire-and-forget
127 call. If you wish confirmation of the handler() being successfully
128 invoked, you must ensure it replies to the caller in some way.
129 Because of asynchronous nature of this call, the nature of the
131 parameter passed to the destination thread has some restructions. If
132 you don't need parameters, merely pass NULL as the value of void
133 **pp_private_data.
134 If you wish to pass a pointer to data between the threads, it MUST be a
136 pointer to a talloced pointer, which is not part of a talloc-pool, and
137 it must not have a destructor attached. The ownership of the memory
138 pointed to will be passed from the calling thread to the tevent
139 library, and if the receiving thread does not talloc-reparent it to its
140 own contexts, it will be freed once the handler is called.
141 On success, *pp_private will be NULL to signify the talloc memory
143 ownership has been moved.
144 In practice for message passing between threads in event loops these
146 restrictions are not very onerous.
147 The easiest way to to a request-reply pair between tevent loops on
149 different threads is to pass the parameter block of memory back and
150 forth using a reply tevent_thread_proxy_schedule() call.
151 Here is an example (without error checking for simplicity):
153 ------------------------------------------------
155 // Master thread.
156 main()
158 {
159 // Make talloc thread-safe.
160 talloc_disable_null_tracking();
162 // Create the master event context.
164 struct tevent_context *master_ev = tevent_context_init(NULL);
166 // Create the master thread proxy to allow it to receive
168 // async callbacks from other threads.
169 struct tevent_thread_proxy *master_tp =
171 tevent_thread_proxy_create(master_ev);
172 // Create sub-threads, passing master_tp in
174 // some way to them.
175 // This code not shown..
176 // Process events.
178 // Function master_callback() below
179 // will be invoked on this thread on
180 // master_ev event context.
181 tevent_loop_wait(master_ev);
183 // Cleanup if loop exits.
185 talloc_free(master_ev);
187 }
188 // Data passed between threads.
190 struct reply_state {
191 struct tevent_thread_proxy *reply_tp;
192 pthread_t thread_id;
193 bool *p_finished;
194 };
195 // Callback Called in child thread context.
197 static void thread_callback(struct tevent_context *ev,
199 struct tevent_immediate *im,
200 void *private_ptr)
201 {
202 // Move the ownership of what private_ptr
203 // points to from the tevent library back to this thread.
204 struct reply_state *rsp =
206 talloc_get_type_abort(private_ptr, struct reply_state);
207 talloc_steal(ev, rsp);
209 *rsp->p_finished = true;
211 // im will be talloc_freed on return from this call.
213 // but rsp will not.
214 }
215 // Callback Called in master thread context.
217 static void master_callback(struct tevent_context *ev,
219 struct tevent_immediate *im,
220 void *private_ptr)
221 {
222 // Move the ownership of what private_ptr
223 // points to from the tevent library to this thread.
224 struct reply_state *rsp =
226 talloc_get_type_abort(private_ptr, struct reply_state);
227 talloc_steal(ev, rsp);
229 printf("Callback from thread %s0, thread_id_to_string(rsp->thread_id));
231 /* Now reply to the thread ! */
233 tevent_thread_proxy_schedule(rsp->reply_tp,
234 &im,
235 thread_callback,
236 &rsp);
237 // Note - rsp and im are now NULL as the tevent library
239 // owns the memory.
240 }
241 // Child thread.
243 static void *thread_fn(void *private_ptr)
245 {
246 struct tevent_thread_proxy *master_tp =
247 talloc_get_type_abort(private_ptr, struct tevent_thread_proxy);
248 bool finished = false;
249 int ret;
250 // Create our own event context.
252 struct tevent_context *ev = tevent_context_init(NULL);
254 // Create the local thread proxy to allow us to receive
256 // async callbacks from other threads.
257 struct tevent_thread_proxy *local_tp =
259 tevent_thread_proxy_create(master_ev);
260 // Setup the data to send.
262 struct reply_state *rsp = talloc(ev, struct reply_state);
264 rsp->reply_tp = local_tp;
266 rsp->thread_id = pthread_self();
267 rsp->p_finished = &finished;
268 // Create the immediate event to use.
270 struct tevent_immediate *im = tevent_create_immediate(ev);
272 // Call the master thread.
274 tevent_thread_proxy_schedule(master_tp,
276 &im,
277 master_callback,
278 &rsp);
279 // Note - rsp and im are now NULL as the tevent library
281 // owns the memory.
282 // Wait for the reply.
284 while (!finished) {
286 tevent_loop_once(ev);
287 }
288 // Cleanup.
290 talloc_free(ev);
292 return NULL;
293 }
294 Note this doesn't have to be a master-subthread communication. Any
296 thread that has access to the struct tevent_thread_proxy * pointer of
297 another thread that has called tevent_thread_proxy_create() can send
298 an async tevent_immediate request.
299 But remember the caveat that external synchronization must be used to
301 ensure the target struct tevent_thread_proxy * object exists at the
302 time of the tevent_thread_proxy_schedule() call or unreproducible
303 crashes will result.
304Version 0.9.8 Sat May 11 2019 tevent_thread(3)