/src/curl/lib/thrdqueue.h

Source
#ifndef HEADER_CURL_THRDQUEUE_H
#define HEADER_CURL_THRDQUEUE_H
/***************************************************************************
 *                                  _   _ ____  _
 *  Project                     ___| | | |  _ \| |
 *                             / __| | | | |_) | |
 *                            | (__| |_| |  _ <| |___
 *                             \___|\___/|_| \_\_____|
 *
 * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution. The terms
 * are also available at https://curl.se/docs/copyright.html.
 *
 * You may opt to use, copy, modify, merge, publish, distribute and/or sell
 * copies of the Software, and permit persons to whom the Software is
 * furnished to do so, under the terms of the COPYING file.
 *
 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
 * KIND, either express or implied.
 *
 * SPDX-License-Identifier: curl
 *
 ***************************************************************************/
#include "curl_setup.h"
#include "curlx/timediff.h"

struct curl_thrdq;

#ifdef USE_THREADS

struct Curl_easy;

typedef enum {
  CURL_THRDQ_EV_ITEM_DONE /* an item has been processed and is ready */
} Curl_thrdq_event;

/* Notification callback when "events" happen in the queue. May be called from
 * any thread, queue is not locked. */
typedef void Curl_thrdq_ev_cb(const struct curl_thrdq *tqueue,
                              Curl_thrdq_event ev,
                              void *user_data);

/* Process a queued item. May be called from any thread. Queue is not
 * locked. */
typedef void Curl_thrdq_item_process_cb(void *item);

/* Free an item. May be called from any thread at any time for an
 * item that is in the queue (either before or after processing). */
typedef void Curl_thrdq_item_free_cb(void *item);

/* Create a new queue processing "items" by a thread pool.
 */
CURLcode Curl_thrdq_create(struct curl_thrdq **ptqueue,
                           const char *name,
                           uint32_t min_threads,
                           uint32_t max_threads,
                           uint32_t idle_time_ms,
                           Curl_thrdq_item_free_cb *fn_free,
                           Curl_thrdq_item_process_cb *fn_process,
                           Curl_thrdq_ev_cb *fn_event, /* optional */
                           void *user_data);

/* Destroy the queue, free all queued items unprocessed and destroy
 * the thread pool used.
 * @param join TRUE when thread pool shall be joined. FALSE for
 *             detaching any running threads.
 */
void Curl_thrdq_destroy(struct curl_thrdq *tqueue, bool join);

/* Send "item" onto the queue. The caller needs to clear any reference
 * to "item" on success, e.g. the queue takes ownership.
 * `description` is an optional string describing the item for tracing
 * purposes. It needs to have the same lifetime as `item`.
 *
 * With`timeout_ms` != 0, items that get stuck that long in the send
 * queue are removed and added to the receive queue right away.
 */
CURLcode Curl_thrdq_send(struct curl_thrdq *tqueue, void *item,
                         const char *description, timediff_t timeout_ms);

/* Receive the oldest, processed item from the queue again, if there is one.
 * The caller takes ownership of the item received, e.g. the queue
 * relinquishes all references to item.
 * Returns CURLE_AGAIN when there is no processed item, setting `pitem`
 * to NULL. When nothing has been processed while items await sending,
 * the pool is signalled to make sure a worker thread exists: an
 * earlier thread start may have failed.
 */
CURLcode Curl_thrdq_recv(struct curl_thrdq *tqueue, void **pitem);

/* Check that items awaiting processing have a worker thread to run
 * them, signalling the pool to start one when needed -- an earlier
 * thread start may have failed. Returns TRUE when everything is ok:
 * no items are waiting or the pool took the signal. FALSE when a
 * thread start just failed again; callers may want to check again
 * soon rather than wait indefinitely.
 */
bool Curl_thrdq_check_started(struct curl_thrdq *tqueue);

/* Return TRUE if the passed "item" matches. */
typedef bool Curl_thrdq_item_match_cb(void *item, void *match_data);

/* Clear all scheduled/processed items that match from the queue. This
 * will *not* be able to clear items that are being processed.
 */
void Curl_thrdq_clear(struct curl_thrdq *tqueue,
                      Curl_thrdq_item_match_cb *fn_match,
                      void *match_data);

CURLcode Curl_thrdq_await_done(struct curl_thrdq *tqueue,
                               uint32_t timeout_ms);

CURLcode Curl_thrdq_set_props(struct curl_thrdq *tqueue,
                              uint32_t min_threads,
                              uint32_t max_threads,
                              uint32_t idle_time_ms);

#ifdef CURLVERBOSE
void Curl_thrdq_trace(struct curl_thrdq *tqueue,
                      struct Curl_easy *data);
#define CURL_THRDQ_TRACE(t, d) \
  do { \
    if(Curl_trc_ft_is_verbose(d, &Curl_trc_feat_threads)) \
      Curl_thrdq_trace(t, d); \
  } while(0)
#else
#define CURL_THRDQ_TRACE(t, d)  Curl_nop_stmt
#endif

#endif /* USE_THREADS */

#endif /* HEADER_CURL_THRDQUEUE_H */

Line	Count	Source
1		#ifndef HEADER_CURL_THRDQUEUE_H
2		#define HEADER_CURL_THRDQUEUE_H
3		/***************************************************************************
4		* _ _ ____ _
5		* Project ___\| \| \| \| _ \\| \|
6		* / __\| \| \| \| \|_) \| \|
7		* \| (__\| \|_\| \| _ <\| \|___
8		* \___\|\___/\|_\| \_\_____\|
9		*
10		* Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
11		*
12		* This software is licensed as described in the file COPYING, which
13		* you should have received as part of this distribution. The terms
14		* are also available at https://curl.se/docs/copyright.html.
15		*
16		* You may opt to use, copy, modify, merge, publish, distribute and/or sell
17		* copies of the Software, and permit persons to whom the Software is
18		* furnished to do so, under the terms of the COPYING file.
19		*
20		* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
21		* KIND, either express or implied.
22		*
23		* SPDX-License-Identifier: curl
24		*
25		***************************************************************************/
26		#include "curl_setup.h"
27		#include "curlx/timediff.h"
28
29		struct curl_thrdq;
30
31		#ifdef USE_THREADS
32
33		struct Curl_easy;
34
35		typedef enum {
36		CURL_THRDQ_EV_ITEM_DONE /* an item has been processed and is ready */
37		} Curl_thrdq_event;
38
39		/* Notification callback when "events" happen in the queue. May be called from
40		* any thread, queue is not locked. */
41		typedef void Curl_thrdq_ev_cb(const struct curl_thrdq *tqueue,
42		Curl_thrdq_event ev,
43		void *user_data);
44
45		/* Process a queued item. May be called from any thread. Queue is not
46		* locked. */
47		typedef void Curl_thrdq_item_process_cb(void *item);
48
49		/* Free an item. May be called from any thread at any time for an
50		* item that is in the queue (either before or after processing). */
51		typedef void Curl_thrdq_item_free_cb(void *item);
52
53		/* Create a new queue processing "items" by a thread pool.
54		*/
55		CURLcode Curl_thrdq_create(struct curl_thrdq **ptqueue,
56		const char *name,
57		uint32_t min_threads,
58		uint32_t max_threads,
59		uint32_t idle_time_ms,
60		Curl_thrdq_item_free_cb *fn_free,
61		Curl_thrdq_item_process_cb *fn_process,
62		Curl_thrdq_ev_cb fn_event, / optional */
63		void *user_data);
64
65		/* Destroy the queue, free all queued items unprocessed and destroy
66		* the thread pool used.
67		* @param join TRUE when thread pool shall be joined. FALSE for
68		* detaching any running threads.
69		*/
70		void Curl_thrdq_destroy(struct curl_thrdq *tqueue, bool join);
71
72		/* Send "item" onto the queue. The caller needs to clear any reference
73		* to "item" on success, e.g. the queue takes ownership.
74		* `description` is an optional string describing the item for tracing
75		* purposes. It needs to have the same lifetime as `item`.
76		*
77		* With`timeout_ms` != 0, items that get stuck that long in the send
78		* queue are removed and added to the receive queue right away.
79		*/
80		CURLcode Curl_thrdq_send(struct curl_thrdq tqueue, void item,
81		const char *description, timediff_t timeout_ms);
82
83		/* Receive the oldest, processed item from the queue again, if there is one.
84		* The caller takes ownership of the item received, e.g. the queue
85		* relinquishes all references to item.
86		* Returns CURLE_AGAIN when there is no processed item, setting `pitem`
87		* to NULL. When nothing has been processed while items await sending,
88		* the pool is signalled to make sure a worker thread exists: an
89		* earlier thread start may have failed.
90		*/
91		CURLcode Curl_thrdq_recv(struct curl_thrdq tqueue, void *pitem);
92
93		/* Check that items awaiting processing have a worker thread to run
94		* them, signalling the pool to start one when needed -- an earlier
95		* thread start may have failed. Returns TRUE when everything is ok:
96		* no items are waiting or the pool took the signal. FALSE when a
97		* thread start just failed again; callers may want to check again
98		* soon rather than wait indefinitely.
99		*/
100		bool Curl_thrdq_check_started(struct curl_thrdq *tqueue);
101
102		/* Return TRUE if the passed "item" matches. */
103		typedef bool Curl_thrdq_item_match_cb(void item, void match_data);
104
105		/* Clear all scheduled/processed items that match from the queue. This
106		* will not be able to clear items that are being processed.
107		*/
108		void Curl_thrdq_clear(struct curl_thrdq *tqueue,
109		Curl_thrdq_item_match_cb *fn_match,
110		void *match_data);
111
112		CURLcode Curl_thrdq_await_done(struct curl_thrdq *tqueue,
113		uint32_t timeout_ms);
114
115		CURLcode Curl_thrdq_set_props(struct curl_thrdq *tqueue,
116		uint32_t min_threads,
117		uint32_t max_threads,
118		uint32_t idle_time_ms);
119
120		#ifdef CURLVERBOSE
121		void Curl_thrdq_trace(struct curl_thrdq *tqueue,
122		struct Curl_easy *data);
123		#define CURL_THRDQ_TRACE(t, d) \
124	53.8k	do { \
125	53.8k	if(Curl_trc_ft_is_verbose(d, &Curl_trc_feat_threads)) \
126	53.8k	Curl_thrdq_trace(t, d); \
127	53.8k	} while(0)
128		#else
129		#define CURL_THRDQ_TRACE(t, d) Curl_nop_stmt
130		#endif
131
132		#endif /* USE_THREADS */
133
134		#endif /* HEADER_CURL_THRDQUEUE_H */

Coverage Report

Created: 2026-10-15 06:19