buffer.h File Reference

Buffering configuration. More...

#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	udipe_buffer_config_s
struct	udipe_buffer_configurator_s

Macros
#define	UDIPE_MAX_BUFFERS   ((size_t)64)

Typedefs
typedef struct udipe_buffer_config_s	udipe_buffer_config_t
typedef udipe_buffer_config_t(*	udipe_buffer_config_callback_t) (void *)
typedef struct udipe_buffer_configurator_s	udipe_buffer_configurator_t

Detailed Description

This header is the home of udipe_buffer_config_t, the data structure that configures the buffering policy of libudipe worker threads, along with related type and constant definitions.

Macro Definition Documentation

UDIPE_MAX_BUFFERS

#define UDIPE_MAX_BUFFERS   ((size_t)64)

Maximum number of buffers that a worker thread can manage

Any attempt to set up a worker thread that manages more than this amount of buffers will fail.

If automatic configuration logic determines that the optimal amount of buffers is above this limit, then it will log a warning and stick with this amount of buffers.

Typedef Documentation

udipe_buffer_config_callback_t

typedef udipe_buffer_config_t(* udipe_buffer_config_callback_t) (void *)

Worker thread memory management configuration callback

You may specify such a callback as part of udipe_buffer_configurator_t in order to tune the buffering policy of individual libudipe worker threads.

It will be invoked by each worker thread on startup (and must therefore be thread-safe since worker threads start concurrently), and it is responsible for returning a udipe_buffer_config_t that adjusts the worker thread's buffering policy. See the documentation of this struct for more info on available tunable parameters.

The input void* parameter is of your choosing. It is specified via udipe_buffer_configurator_t::context and passed in as is to each invocation of the callback. You can use it to pass any information that your callback needs to compute its memory management configuration. For example...

• When you want to configure all threads in the same manner, you can use it to pass in a const udipe_buffer_config_t* that points to the parameters shared by all threads.
• When you want to configure threads in a cache locality aware manner, you can use it to pass in external context (e.g. a hwloc_topology_t) that is used to figure out relevant cache parameters for the active thread.

The intent behind this callback-based design is to let you...

• Adapt to the fact that the number of worker threads that libudipe will spawn, and their pinning to CPU cores or lack thereof, is an opaque implementation detail of libudipe.
• Adjust the tuning parameters on a per-thread basis, which can make sense on systems with heterogeneous CPU cores.

udipe_buffer_config_t

typedef struct udipe_buffer_config_s udipe_buffer_config_t

Tunable buffering parameters for one worker thread

This is the value returned by the udipe_buffer_config_callback_t for each worker thread, used to tune each thread's memory management policy.

udipe_buffer_configurator_t

typedef struct udipe_buffer_configurator_s udipe_buffer_configurator_t

Memory management configuration

This struct can be used to control the memory management policy of libudipe.

Examples

configure_buffering.c.