#$@%#$%!

Ngiler SH3LL 360
: / usr / include / fstrm /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : iothr.h \| Size : 15.12 KB
/* * Copyright (c) 2014 by Farsight Security, Inc. * * Permission is hereby granted, free of charge, to any person obtaining * a copy of this software and associated documentation files (the * "Software"), to deal in the Software without restriction, including * without limitation the rights to use, copy, modify, merge, publish, * distribute, sublicense, and/or sell copies of the Software, and to * permit persons to whom the Software is furnished to do so, subject to * the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * / #ifndef FSTRM_IOTHR_H #define FSTRM_IOTHR_H /* * \defgroup fstrm_iothr fstrm_iothr * * The `fstrm_iothr` interface creates a background I/O thread which writes * Frame Streams encapsulated data frames into an output stream specified by an * \ref fstrm_writer object. It exposes non-blocking input queues that can be * used by worker threads to asynchronously write data frames to the output * stream. A deferred deallocation callback is invoked after the I/O thread has * disposed of a queued data frame. * * In order to create an `fstrm_iothr` object, the caller must first configure * and instantiate an `fstrm_writer` object and pass this instance to the * fstrm_iothr_init() function. The `fstrm_iothr` object then takes ownership of * the `fstrm_writer` object. It is responsible for serializing writes and will * take care of destroying the captive `fstrm_writer` object at the same time * the `fstrm_iothr` object is destroyed. The caller should not perform any * operations on the captive `fstrm_writer` object after it has been passed to * `fstrm_iothr_init()`. * * Parameters used to configure the I/O thread are passed through an * `fstrm_iothr_options` object. These options have to be specified in advance * and are mostly performance knobs which have reasonable defaults. * * Once the `fstrm_iothr` object has been created, handles to the input queues * used to submit data frames can be obtained by calling * `fstrm_iothr_get_input_queue()`. This function can be called up to * num_input_queues times, and can be safely called concurrently. For * instance, in an application with a fixed number of worker threads, an input * queue can be dedicated to each worker thread by setting the * num_input_queues option to the number of worker threads, and then calling * `fstrm_iothr_get_input_queue()` from each worker thread's startup function to * obtain a per-thread input queue. * * @{ / /* * Initialize an `fstrm_iothr_options` object. This is needed to pass * configuration parameters to fstrm_iothr_init(). * * \return * `fstrm_iothr_options` object. / struct fstrm_iothr_options fstrm_iothr_options_init(void); /** * Destroy an `fstrm_iothr_options` object. * * \param opt * Pointer to `fstrm_iothr_options` object. / void fstrm_iothr_options_destroy(struct fstrm_iothr_options opt); /* * Set the `buffer_hint` parameter. This is the threshold number of bytes to * accumulate in the output buffer before forcing a buffer flush. * * \param opt * `fstrm_iothr_options` object. * \param buffer_hint * New `buffer_hint` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_buffer_hint( struct fstrm_iothr_options opt, unsigned buffer_hint); /** Minimum `buffer_hint` value. / #define FSTRM_IOTHR_BUFFER_HINT_MIN 1024 /* Default `buffer_hint` value. / #define FSTRM_IOTHR_BUFFER_HINT_DEFAULT 8192 /* Maximum `buffer_hint` value. / #define FSTRM_IOTHR_BUFFER_HINT_MAX 65536 /* * Set the `flush_timeout` parameter. This is the number of seconds to allow * unflushed data to remain in the output buffer. * * \param opt * `fstrm_iothr_options` object. * \param flush_timeout * New `flush_timeout` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_flush_timeout( struct fstrm_iothr_options opt, unsigned flush_timeout); /** Minimum `flush_timeout` value. / #define FSTRM_IOTHR_FLUSH_TIMEOUT_MIN 1 /* Default `flush_timeout` value. / #define FSTRM_IOTHR_FLUSH_TIMEOUT_DEFAULT 1 /* Maximum `flush_timeout` value. / #define FSTRM_IOTHR_FLUSH_TIMEOUT_MAX 600 /* * Set the `input_queue_size` parameter. This is the number of queue entries to * allocate per each input queue. This option controls the number of outstanding * data frames per input queue that can be outstanding for deferred processing * by the `fstrm_iothr` object and thus affects performance and memory usage. * * This parameter must be a power-of-2. * * \param opt * `fstrm_iothr_options` object. * \param input_queue_size * New `input_queue_size` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_input_queue_size( struct fstrm_iothr_options opt, unsigned input_queue_size); /** Minimum `input_queue_size` value. / #define FSTRM_IOTHR_INPUT_QUEUE_SIZE_MIN 2 /* Default `input_queue_size` value. / #define FSTRM_IOTHR_INPUT_QUEUE_SIZE_DEFAULT 512 /* Maximum `input_queue_size` value. / #define FSTRM_IOTHR_INPUT_QUEUE_SIZE_MAX 16384 /* * Set the `num_input_queues` parameter. This is the number of input queues to * create and must match the number of times that fstrm_iothr_get_input_queue() * is called on the corresponding `fstrm_iothr` object. * * \param opt * `fstrm_iothr_options` object. * \param num_input_queues * New `num_input_queues` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_num_input_queues( struct fstrm_iothr_options opt, unsigned num_input_queues); /** Minimum `num_input_queues` value. / #define FSTRM_IOTHR_NUM_INPUT_QUEUES_MIN 1 /* Default `num_input_queues` value. / #define FSTRM_IOTHR_NUM_INPUT_QUEUES_DEFAULT 1 /* * Set the `output_queue_size` parameter. This is the number of queue entries to * allocate for the output queue. This option controls the maximum number of * data frames that can be accumulated in the output queue before a buffer flush * must occur and thus affects performance and memory usage. * * \param opt * `fstrm_iothr_options` object. * \param output_queue_size * New `output_queue_size` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_output_queue_size( struct fstrm_iothr_options opt, unsigned output_queue_size); /** Minimum `output_queue_size` value. / #define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_MIN 2 /* Default `output_queue_size` value. / #define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_DEFAULT 64 /* Maximum `output_queue_size` value. / #define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_MAX IOV_MAX /* * Queue models. * \see fstrm_iothr_options_set_queue_model() / typedef enum { /* Single Producer, Single Consumer. / FSTRM_IOTHR_QUEUE_MODEL_SPSC, /* Multiple Producer, Single Consumer. / FSTRM_IOTHR_QUEUE_MODEL_MPSC, } fstrm_iothr_queue_model; /* * Set the `queue_model` parameter. This controls what queueing semantics to use * for `fstrm_iothr_queue` objects. Single Producer queues * (#FSTRM_IOTHR_QUEUE_MODEL_SPSC) may only have a single thread at a time * calling fstrm_iothr_submit() on a given `fstrm_iothr_queue` object, while * Multiple Producer queues (#FSTRM_IOTHR_QUEUE_MODEL_MPSC) may have multiple * threads concurrently calling fstrm_iothr_submit() on a given * `fstrm_iothr_queue` object. * * \param opt * `fstrm_iothr_options` object. * \param queue_model * New `queue_model` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_queue_model( struct fstrm_iothr_options opt, fstrm_iothr_queue_model queue_model); /** Default `queue_model` value. / #define FSTRM_IOTHR_QUEUE_MODEL_DEFAULT FSTRM_IOTHR_QUEUE_MODEL_SPSC /* * Set the `queue_notify_threshold` parameter. This controls the number of * outstanding queue entries to allow on an input queue before waking the I/O * thread, which will cause the outstanding queue entries to begin draining. * * \param opt * `fstrm_iothr_options` object. * \param queue_notify_threshold * New `queue_notify_threshold` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_queue_notify_threshold( struct fstrm_iothr_options opt, unsigned queue_notify_threshold); /** Minimum `queue_notify_threshold` value. / #define FSTRM_IOTHR_QUEUE_NOTIFY_THRESHOLD_MIN 1 /* Default `queue_notify_threshold` value. / #define FSTRM_IOTHR_QUEUE_NOTIFY_THRESHOLD_DEFAULT 32 /* * Set the `reopen_interval` parameter. This controls the number of seconds to * wait between attempts to reopen a closed `fstrm_writer` output stream. * * \param opt * `fstrm_iothr_options` object. * \param reopen_interval * New `queue_notify_threshold` value. * * \retval #fstrm_res_success * \retval #fstrm_res_failure / fstrm_res fstrm_iothr_options_set_reopen_interval( struct fstrm_iothr_options opt, unsigned reopen_interval); /** Minimum `reopen_interval` value. / #define FSTRM_IOTHR_REOPEN_INTERVAL_MIN 1 /* Default `reopen_interval` value. / #define FSTRM_IOTHR_REOPEN_INTERVAL_DEFAULT 5 /* Maximum `reopen_interval` value. / #define FSTRM_IOTHR_REOPEN_INTERVAL_MAX 600 /* * Initialize an `fstrm_iothr` object. This creates a background I/O thread * which asynchronously writes data frames submitted by other threads which call * fstrm_iothr_submit(). * * \param opt * `fstrm_iothr_options` object. May be NULL, in which case default values * will be used. * * \param writer * Pointer to `fstrm_writer` object. Must be non-NULL. * * \return * `fstrm_iothr` object. * \retval * NULL on failure. / struct fstrm_iothr fstrm_iothr_init( const struct fstrm_iothr_options opt, struct fstrm_writer writer); /* * Destroy an `fstrm_iothr` object. This signals the background I/O thread to * flush or discard any queued data frames and deallocates any resources used * internally. This function blocks until the I/O thread has terminated. * * \param iothr * Pointer to `fstrm_iothr` object. / void fstrm_iothr_destroy(struct fstrm_iothr iothr); /* * Obtain an `fstrm_iothr_queue` object for submitting data frames to the * `fstrm_iothr` object. `fstrm_iothr_queue` objects are child objects of their * parent `fstrm_iothr` object and will be destroyed when fstrm_iothr_destroy() * is called on the parent `fstrm_iothr` object. * * This function is thread-safe and may be called simultaneously from any * thread. For example, in a program which employs a fixed number of worker * threads to handle requests, fstrm_iothr_get_input_queue() may be called from * a thread startup routine without synchronization. * * `fstrm_iothr` objects allocate a fixed total number of `fstrm_iothr_queue` * objects during the call to fstrm_iothr_init(). To adjust this parameter, use * fstrm_iothr_options_set_num_input_queues(). * * This function will fail if it is called more than num_input_queues times. * By default, only one input queue is initialized per `fstrm_iothr` object. * * For optimum performance in a threaded program, each worker thread submitting * data frames should have a dedicated `fstrm_iothr_queue` object. This allows * each worker thread to have its own queue which is processed independently by * the I/O thread. If the queue model for the `fstrm_iothr` object is set to * #FSTRM_IOTHR_QUEUE_MODEL_SPSC, this results in contention-free access to the * input queue. * * \param iothr * `fstrm_iothr` object. * * \return * `fstrm_iothr_queue` object. * \retval * NULL on failure. / struct fstrm_iothr_queue fstrm_iothr_get_input_queue(struct fstrm_iothr iothr); /* * Obtain an `fstrm_iothr_queue` object for submitting data frames to the * `fstrm_iothr` object. This function is like fstrm_iothr_get_input_queue() * except it indexes into the `fstrm_iothr_queue`'s array of input queues. * * \param iothr * `fstrm_iothr` object. * \param idx * Index of the `fstrm_iothr_queue` object to retrieve. This value is * limited by the num_input_queues option. * * \return * `fstrm_iothr_queue` object. * \retval * NULL on failure. / struct fstrm_iothr_queue fstrm_iothr_get_input_queue_idx(struct fstrm_iothr iothr, size_t idx); /* * Submit a data frame to the background I/O thread. If successfully queued and * the I/O thread has an active output stream opened, the data frame will be * asynchronously written to the output stream. * * When this function returns #fstrm_res_success, responsibility for * deallocating the data frame specified by the `data` parameter passes to the * `fstrm` library. The caller MUST ensure that the `data` object remains * valid after fstrm_iothr_submit() returns. The callback function specified by * the `free_func` parameter will be invoked once the data frame is no longer * needed by the `fstrm` library. For example, if the data frame is dynamically * allocated, the data frame may be deallocated in the callback function. * * Note that if this function returns #fstrm_res_failure, the responsibility for * deallocating the data frame remains with the caller. * * As a convenience, if `data` is allocated with the system's `malloc()`, * `fstrm_free_wrapper` may be provided as the `free_func` parameter with the * `free_data` parameter set to `NULL`. This will cause the system's `free()` to * be invoked to deallocate `data`. * * `free_func` may be NULL, in which case no callback function will be invoked * to dispose of `buf`. This behavior may be useful if `data` is a global, * statically allocated object. * * \param iothr * `fstrm_iothr` object. * \param ioq * `fstrm_iothr_queue` object. * \param data * Data frame bytes. * \param len * Number of bytes in `data`. * \param free_func * Callback function to deallocate the data frame. The `data` and * `free_data` parameters passed to this callback will be the same values * originally supplied in the call to fstrm_iothr_submit(). * \param free_data * Parameter to pass to `free_func`. * * \retval #fstrm_res_success * The data frame was successfully queued. * \retval #fstrm_res_again * The queue is full. * \retval #fstrm_res_failure * Permanent failure. / fstrm_res fstrm_iothr_submit( struct fstrm_iothr iothr, struct fstrm_iothr_queue ioq, void data, size_t len, void (free_func)(void buf, void free_data), void free_data); /** * Wrapper function for the system's `free()`, suitable for use as the * `free_func` callback for fstrm_iothr_submit(). * * \param data * Object to call `free()` on. * \param free_data * Unused. / void fstrm_free_wrapper(void data, void free_data); /@}/ #endif /* FSTRM_IOTHR_H */ Back

Edit File : iothr.h | Size : 15.12 KB

/*
 * Copyright (c) 2014 by Farsight Security, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 */

#ifndef FSTRM_IOTHR_H
#define FSTRM_IOTHR_H

/**
 * \defgroup fstrm_iothr fstrm_iothr
 *
 * The `fstrm_iothr` interface creates a background I/O thread which writes
 * Frame Streams encapsulated data frames into an output stream specified by an
 * \ref fstrm_writer object. It exposes non-blocking input queues that can be
 * used by worker threads to asynchronously write data frames to the output
 * stream. A deferred deallocation callback is invoked after the I/O thread has
 * disposed of a queued data frame.
 *
 * In order to create an `fstrm_iothr` object, the caller must first configure
 * and instantiate an `fstrm_writer` object and pass this instance to the
 * fstrm_iothr_init() function. The `fstrm_iothr` object then takes ownership of
 * the `fstrm_writer` object. It is responsible for serializing writes and will
 * take care of destroying the captive `fstrm_writer` object at the same time
 * the `fstrm_iothr` object is destroyed. The caller should not perform any
 * operations on the captive `fstrm_writer` object after it has been passed to
 * `fstrm_iothr_init()`.
 *
 * Parameters used to configure the I/O thread are passed through an
 * `fstrm_iothr_options` object. These options have to be specified in advance
 * and are mostly performance knobs which have reasonable defaults.
 *
 * Once the `fstrm_iothr` object has been created, handles to the input queues
 * used to submit data frames can be obtained by calling
 * `fstrm_iothr_get_input_queue()`. This function can be called up to
 * **num_input_queues** times, and can be safely called concurrently. For
 * instance, in an application with a fixed number of worker threads, an input
 * queue can be dedicated to each worker thread by setting the
 * **num_input_queues** option to the number of worker threads, and then calling
 * `fstrm_iothr_get_input_queue()` from each worker thread's startup function to
 * obtain a per-thread input queue.
 *
 * @{
 */

/**
 * Initialize an `fstrm_iothr_options` object. This is needed to pass
 * configuration parameters to fstrm_iothr_init().
 *
 * \return
 *	`fstrm_iothr_options` object.
 */
struct fstrm_iothr_options *
fstrm_iothr_options_init(void);

/**
 * Destroy an `fstrm_iothr_options` object.
 *
 * \param opt
 *	Pointer to `fstrm_iothr_options` object.
 */
void
fstrm_iothr_options_destroy(struct fstrm_iothr_options **opt);

/**
 * Set the `buffer_hint` parameter. This is the threshold number of bytes to
 * accumulate in the output buffer before forcing a buffer flush.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param buffer_hint
 *	New `buffer_hint` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_buffer_hint(
	struct fstrm_iothr_options *opt,
	unsigned buffer_hint);

/** Minimum `buffer_hint` value. */
#define FSTRM_IOTHR_BUFFER_HINT_MIN			1024

/** Default `buffer_hint` value. */
#define FSTRM_IOTHR_BUFFER_HINT_DEFAULT			8192

/** Maximum `buffer_hint` value. */
#define FSTRM_IOTHR_BUFFER_HINT_MAX			65536

/**
 * Set the `flush_timeout` parameter. This is the number of seconds to allow
 * unflushed data to remain in the output buffer.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param flush_timeout
 *	New `flush_timeout` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_flush_timeout(
	struct fstrm_iothr_options *opt,
	unsigned flush_timeout);

/** Minimum `flush_timeout` value. */
#define FSTRM_IOTHR_FLUSH_TIMEOUT_MIN			1

/** Default `flush_timeout` value. */
#define FSTRM_IOTHR_FLUSH_TIMEOUT_DEFAULT		1

/** Maximum `flush_timeout` value. */
#define FSTRM_IOTHR_FLUSH_TIMEOUT_MAX			600

/**
 * Set the `input_queue_size` parameter. This is the number of queue entries to
 * allocate per each input queue. This option controls the number of outstanding
 * data frames per input queue that can be outstanding for deferred processing
 * by the `fstrm_iothr` object and thus affects performance and memory usage.
 *
 * This parameter must be a power-of-2.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param input_queue_size
 *	New `input_queue_size` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_input_queue_size(
	struct fstrm_iothr_options *opt,
	unsigned input_queue_size);

/** Minimum `input_queue_size` value. */
#define FSTRM_IOTHR_INPUT_QUEUE_SIZE_MIN		2

/** Default `input_queue_size` value. */
#define FSTRM_IOTHR_INPUT_QUEUE_SIZE_DEFAULT		512

/** Maximum `input_queue_size` value. */
#define FSTRM_IOTHR_INPUT_QUEUE_SIZE_MAX		16384

/**
 * Set the `num_input_queues` parameter. This is the number of input queues to
 * create and must match the number of times that fstrm_iothr_get_input_queue()
 * is called on the corresponding `fstrm_iothr` object.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param num_input_queues
 *	New `num_input_queues` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_num_input_queues(
	struct fstrm_iothr_options *opt,
	unsigned num_input_queues);

/** Minimum `num_input_queues` value. */
#define FSTRM_IOTHR_NUM_INPUT_QUEUES_MIN		1

/** Default `num_input_queues` value. */
#define FSTRM_IOTHR_NUM_INPUT_QUEUES_DEFAULT		1

/**
 * Set the `output_queue_size` parameter. This is the number of queue entries to
 * allocate for the output queue. This option controls the maximum number of
 * data frames that can be accumulated in the output queue before a buffer flush
 * must occur and thus affects performance and memory usage.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param output_queue_size
 *	New `output_queue_size` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_output_queue_size(
	struct fstrm_iothr_options *opt,
	unsigned output_queue_size);

/** Minimum `output_queue_size` value. */
#define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_MIN		2

/** Default `output_queue_size` value. */
#define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_DEFAULT		64

/** Maximum `output_queue_size` value. */
#define FSTRM_IOTHR_OUTPUT_QUEUE_SIZE_MAX		IOV_MAX

/**
 * Queue models.
 * \see fstrm_iothr_options_set_queue_model()
 */
typedef enum {
	/** Single Producer, Single Consumer. */
	FSTRM_IOTHR_QUEUE_MODEL_SPSC,

/** Multiple Producer, Single Consumer. */
	FSTRM_IOTHR_QUEUE_MODEL_MPSC,
} fstrm_iothr_queue_model;

/**
 * Set the `queue_model` parameter. This controls what queueing semantics to use
 * for `fstrm_iothr_queue` objects. Single Producer queues
 * (#FSTRM_IOTHR_QUEUE_MODEL_SPSC) may only have a single thread at a time
 * calling fstrm_iothr_submit() on a given `fstrm_iothr_queue` object, while
 * Multiple Producer queues (#FSTRM_IOTHR_QUEUE_MODEL_MPSC) may have multiple
 * threads concurrently calling fstrm_iothr_submit() on a given
 * `fstrm_iothr_queue` object.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param queue_model
 *	New `queue_model` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_queue_model(
	struct fstrm_iothr_options *opt,
	fstrm_iothr_queue_model queue_model);

/** Default `queue_model` value. */
#define FSTRM_IOTHR_QUEUE_MODEL_DEFAULT			FSTRM_IOTHR_QUEUE_MODEL_SPSC

/**
 * Set the `queue_notify_threshold` parameter. This controls the number of
 * outstanding queue entries to allow on an input queue before waking the I/O
 * thread, which will cause the outstanding queue entries to begin draining.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param queue_notify_threshold
 *	New `queue_notify_threshold` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_queue_notify_threshold(
	struct fstrm_iothr_options *opt,
	unsigned queue_notify_threshold);

/** Minimum `queue_notify_threshold` value. */
#define FSTRM_IOTHR_QUEUE_NOTIFY_THRESHOLD_MIN		1

/** Default `queue_notify_threshold` value. */
#define FSTRM_IOTHR_QUEUE_NOTIFY_THRESHOLD_DEFAULT	32

/**
 * Set the `reopen_interval` parameter. This controls the number of seconds to
 * wait between attempts to reopen a closed `fstrm_writer` output stream.
 *
 * \param opt
 *	`fstrm_iothr_options` object.
 * \param reopen_interval
 *	New `queue_notify_threshold` value.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_iothr_options_set_reopen_interval(
	struct fstrm_iothr_options *opt,
	unsigned reopen_interval);

/** Minimum `reopen_interval` value. */
#define FSTRM_IOTHR_REOPEN_INTERVAL_MIN			1

/** Default `reopen_interval` value. */
#define FSTRM_IOTHR_REOPEN_INTERVAL_DEFAULT		5

/** Maximum `reopen_interval` value. */
#define FSTRM_IOTHR_REOPEN_INTERVAL_MAX			600

/**
 * Initialize an `fstrm_iothr` object. This creates a background I/O thread
 * which asynchronously writes data frames submitted by other threads which call
 * fstrm_iothr_submit().
 *
 * \param opt
 *	`fstrm_iothr_options` object. May be NULL, in which case default values
 *	will be used.
 *
 * \param writer
 *	Pointer to `fstrm_writer` object. Must be non-NULL.
 *
 * \return
 *	`fstrm_iothr` object.
 * \retval
 *	NULL on failure.
 */
struct fstrm_iothr *
fstrm_iothr_init(
	const struct fstrm_iothr_options *opt,
	struct fstrm_writer **writer);

/**
 * Destroy an `fstrm_iothr` object. This signals the background I/O thread to
 * flush or discard any queued data frames and deallocates any resources used
 * internally. This function blocks until the I/O thread has terminated.
 *
 * \param iothr
 *	Pointer to `fstrm_iothr` object.
 */
void
fstrm_iothr_destroy(struct fstrm_iothr **iothr);

/**
 * Obtain an `fstrm_iothr_queue` object for submitting data frames to the
 * `fstrm_iothr` object. `fstrm_iothr_queue` objects are child objects of their
 * parent `fstrm_iothr` object and will be destroyed when fstrm_iothr_destroy()
 * is called on the parent `fstrm_iothr` object.
 *
 * This function is thread-safe and may be called simultaneously from any
 * thread. For example, in a program which employs a fixed number of worker
 * threads to handle requests, fstrm_iothr_get_input_queue() may be called from
 * a thread startup routine without synchronization.
 *
 * `fstrm_iothr` objects allocate a fixed total number of `fstrm_iothr_queue`
 * objects during the call to fstrm_iothr_init(). To adjust this parameter, use
 * fstrm_iothr_options_set_num_input_queues().
 *
 * This function will fail if it is called more than **num_input_queues** times.
 * By default, only one input queue is initialized per `fstrm_iothr` object.
 *
 * For optimum performance in a threaded program, each worker thread submitting
 * data frames should have a dedicated `fstrm_iothr_queue` object. This allows
 * each worker thread to have its own queue which is processed independently by
 * the I/O thread. If the queue model for the `fstrm_iothr` object is set to
 * #FSTRM_IOTHR_QUEUE_MODEL_SPSC, this results in contention-free access to the
 * input queue.
 *
 * \param iothr
 *	`fstrm_iothr` object.
 *
 * \return
 *	`fstrm_iothr_queue` object.
 * \retval
 *	NULL on failure.
 */
struct fstrm_iothr_queue *
fstrm_iothr_get_input_queue(struct fstrm_iothr *iothr);

/**
 * Obtain an `fstrm_iothr_queue` object for submitting data frames to the
 * `fstrm_iothr` object. This function is like fstrm_iothr_get_input_queue()
 * except it indexes into the `fstrm_iothr_queue`'s array of input queues.
 *
 * \param iothr
 *	`fstrm_iothr` object.
 * \param idx
 *	Index of the `fstrm_iothr_queue` object to retrieve. This value is
 *	limited by the **num_input_queues** option.
 *
 * \return
 *	`fstrm_iothr_queue` object.
 * \retval
 *	NULL on failure.
 */
struct fstrm_iothr_queue *
fstrm_iothr_get_input_queue_idx(struct fstrm_iothr *iothr, size_t idx);

/**
 * Submit a data frame to the background I/O thread. If successfully queued and
 * the I/O thread has an active output stream opened, the data frame will be
 * asynchronously written to the output stream.
 *
 * When this function returns #fstrm_res_success, responsibility for
 * deallocating the data frame specified by the `data` parameter passes to the
 * `fstrm` library. The caller **MUST** ensure that the `data` object remains
 * valid after fstrm_iothr_submit() returns. The callback function specified by
 * the `free_func` parameter will be invoked once the data frame is no longer
 * needed by the `fstrm` library. For example, if the data frame is dynamically
 * allocated, the data frame may be deallocated in the callback function.
 *
 * Note that if this function returns #fstrm_res_failure, the responsibility for
 * deallocating the data frame remains with the caller.
 *
 * As a convenience, if `data` is allocated with the system's `malloc()`,
 * `fstrm_free_wrapper` may be provided as the `free_func` parameter with the
 * `free_data` parameter set to `NULL`. This will cause the system's `free()` to
 * be invoked to deallocate `data`.
 *
 * `free_func` may be NULL, in which case no callback function will be invoked
 * to dispose of `buf`. This behavior may be useful if `data` is a global,
 * statically allocated object.
 *
 * \param iothr
 *      `fstrm_iothr` object.
 * \param ioq
 *      `fstrm_iothr_queue` object.
 * \param data
 *      Data frame bytes.
 * \param len
 *      Number of bytes in `data`.
 * \param free_func
 *      Callback function to deallocate the data frame. The `data` and
 *      `free_data` parameters passed to this callback will be the same values
 *      originally supplied in the call to fstrm_iothr_submit().
 * \param free_data
 *      Parameter to pass to `free_func`.
 *
 * \retval #fstrm_res_success
 *      The data frame was successfully queued.
 * \retval #fstrm_res_again
 *      The queue is full.
 * \retval #fstrm_res_failure
 *      Permanent failure.
 */
fstrm_res
fstrm_iothr_submit(
	struct fstrm_iothr *iothr, struct fstrm_iothr_queue *ioq,
	void *data, size_t len,
	void (*free_func)(void *buf, void *free_data), void *free_data);

/**
 * Wrapper function for the system's `free()`, suitable for use as the
 * `free_func` callback for fstrm_iothr_submit().
 *
 * \param data
 *	Object to call `free()` on.
 * \param free_data
 *	Unused.
 */
void
fstrm_free_wrapper(void *data, void *free_data);

/**@}*/

#endif /* FSTRM_IOTHR_H */

Back