lib<mpsc> 0.1.0
A C POSIX multi-thread based multiple producers, single consumer (MPSC) channel library
Loading...
Searching...
No Matches
mpsc.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2024 BB-301 <fw3dg3@gmail.com>
3 [Official repository](https://github.com/BB-301/c-mpsc)
4
5 Permission is hereby granted, free of charge, to any person
6 obtaining a copy of this software and associated documentation
7 files (the “Software”), to deal in the Software without restriction,
8 including without limitation the rights to use, copy, modify, merge,
9 publish, distribute, sublicense, and/or sell copies of the Software,
10 and to permit persons to whom the Software is furnished to do so,
11 subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 THE SOFTWARE.
23*/
24
29#ifndef _MPSC_H_
30#define _MPSC_H_
31
32#include <stdbool.h>
33#include <stddef.h>
34
42typedef enum
43{
67
74typedef struct mpsc_s mpsc_t;
75
80typedef struct mpsc_consumer_s mpsc_consumer_t;
81
86typedef struct mpsc_producer_s mpsc_producer_t;
87
97
123typedef void(mpsc_consumer_callback_t)(mpsc_consumer_t *consumer, void *data, size_t n, bool closed);
124
138
144typedef struct
145{
206
223
234void mpsc_join(mpsc_t *self);
235
249
267
280
293
321bool mpsc_producer_send(mpsc_producer_t *self, void *data, size_t n);
322
340
351
369
370#endif
void void
mpsc_t * mpsc_create(mpsc_create_params_t params)
The function used to create a new channel instance (i.e., a mpsc_t instance).
bool error_handling_enabled
A boolean value indicating whether (true) error handling should be handed over to the application or ...
Definition: mpsc.h:198
mpsc_register_producer_error_t mpsc_register_producer(mpsc_t *self, mpsc_producer_thread_callback_t callback, void *context)
The function used to register a new producer for self .
struct mpsc_producer_s mpsc_producer_t
An opaque data type used as a container for a MPSC channel's producer.
Definition: mpsc.h:86
void() mpsc_consumer_error_callback_t(mpsc_consumer_t *consumer)
The signature of an optional consumer error callback function, to be declared and implemented by the ...
Definition: mpsc.h:137
mpsc_register_producer_error_t mpsc_consumer_register_producer(mpsc_consumer_t *self, mpsc_producer_thread_callback_t callback, void *context)
An alias for mpsc_register_producer , but which is used on an object of type mpsc_consumer_t ,...
struct mpsc_consumer_s mpsc_consumer_t
An opaque data type used as a container for the MPSC channel's consumer.
Definition: mpsc.h:80
void mpsc_join(mpsc_t *self)
The function that must be called on self to wait for the channel close.
bool mpsc_producer_send(mpsc_producer_t *self, void *data, size_t n)
The function used (from inside a producer thread callback function) to send a message to the channel'...
size_t n_max_producers
The maximum number of producers that can be registered on the mpsc_t instance.
Definition: mpsc.h:166
bool create_and_join_thread_safety_disabled
A boolean value that can be used to disable the safety feature that prevents mpsc_create and mpsc_joi...
Definition: mpsc.h:204
void() mpsc_producer_thread_callback_t(mpsc_producer_t *producer)
The signature of the producer thread callback function, to be declared and implemented by the applica...
Definition: mpsc.h:96
bool mpsc_producer_send_empty(mpsc_producer_t *self)
Similar to mpsc_producer_send , except that this function is used (from inside a producer thread call...
bool mpsc_producer_ping(mpsc_producer_t *self)
A function that can be used from inside a producer thread callback to check whether the channel to wh...
void * mpsc_producer_context(mpsc_producer_t *self)
A function that can be used from inside the producer thread callback function to retrieve the applica...
mpsc_consumer_error_callback_t * consumer_error_callback
An optional, application defined producer thread callback function used, when error_handling_enabled ...
Definition: mpsc.h:181
void() mpsc_consumer_callback_t(mpsc_consumer_t *consumer, void *data, size_t n, bool closed)
The signature of the consumer callback function, to be declared and implemented by the application,...
Definition: mpsc.h:123
mpsc_register_producer_error_t
The type returned by mpsc_register_producer (as well as by its aliases; i.e., mpsc_producer_register_...
Definition: mpsc.h:43
@ MPSC_REGISTER_PRODUCER_ERROR_EAGAIN
The producer could not be registered because a EAGAIN error was observed when, internally,...
Definition: mpsc.h:65
@ MPSC_REGISTER_PRODUCER_ERROR_N_MAX_PRODUCERS_REACHED
The producer could not be registered because the maximum number of producers allowed (i....
Definition: mpsc.h:58
@ MPSC_REGISTER_PRODUCER_ERROR_CLOSED
The producer could not be registered because the mpsc_t instance has internally been marked as closed...
Definition: mpsc.h:52
@ MPSC_REGISTER_PRODUCER_ERROR_NONE
The producer was successfully registered.
Definition: mpsc.h:47
struct mpsc_s mpsc_t
An opaque data type used as a container for the MPSC channel data.
Definition: mpsc.h:74
size_t buffer_size
The size (in bytes) of the internal buffer used to transfer a message between a producer and the cons...
Definition: mpsc.h:156
mpsc_register_producer_error_t mpsc_producer_register_producer(mpsc_producer_t *self, mpsc_producer_thread_callback_t callback, void *context)
An alias for mpsc_register_producer , but which is used on an object of type mpsc_producer_t ,...
void mpsc_consumer_close(mpsc_consumer_t *self)
A function that can be used (from inside the application defined consumer callback implementing mpsc_...
mpsc_consumer_callback_t * consumer_callback
The application defined consumer callback function to be used to received messages for the mpsc_t ins...
Definition: mpsc.h:171
The structure that must be passed to mpsc_create to instantiate a new mpsc_t object.
Definition: mpsc.h:145