1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
/*
* Copyright (c) 2017 Cisco and/or its affiliates.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file parc_RingBuffer_1x1.h
* @ingroup threading
* @brief A single producer, single consumer ring buffer
*
* This is useful for synchronizing two (and exactly two) threads in one direction. The
* implementation will use a lock-free algorithm.
*
* Complies with the PARCRingBuffer generic facade.
*
*/
#ifndef libparc_parc_RingBuffer_1x1_h
#define libparc_parc_RingBuffer_1x1_h
#include <stdbool.h>
#include <stdint.h>
struct parc_ringbuffer_1x1;
typedef struct parc_ringbuffer_1x1 PARCRingBuffer1x1;
/**< Will be called for each data item on destroy */
typedef void (RingBufferEntryDestroyer)(void **entryPtr);
/**
* Creates a ring buffer of the given size, which must be a power of 2.
*
* The ring buffer can store up to (elements-1) items in the buffer. The buffer can
* be shared between multiple producers and consumers. Each of them should be
* given out from a call to {@link parcRingBuffer_Acquire} to create reference counted
* copies.
*
* The reference count is "1" on return.
*
* @param [in] elements A power of 2, indicating the maximum size of the buffer.
* @param [in] destroyer Will be called for each ring entry when when the ring is destroyed. May be null.
*
* @return non-null An allocated ring buffer.
*
* Example:
* @code
* <#example#>
* @endcode
*/
PARCRingBuffer1x1 *parcRingBuffer1x1_Create(uint32_t elements, RingBufferEntryDestroyer *destroyer);
/**
* A reference counted copy of the buffer.
*
* A RING WITHOUT LOCKS CAN ONLY HAVE 2 REFERENCES.
*
* @param [in] ring The instance of `PARCRingBuffer1x1` to acquire.
*
* @return non-null A reference counted copy of the ring buffer.
*
* Example:
* @code
* <#example#>
* @endcode
*/
PARCRingBuffer1x1 *parcRingBuffer1x1_Acquire(const PARCRingBuffer1x1 *ring);
/**
* Releases a reference. The buffer will be destroyed after the last release.
*
* If the destroyer was specified on create, it will be called on each entry in the buffer
* when the buffer is destroyed.
*
* @param [in,out] ringPtr The pointer to the pointer of the `PARCRingBuffer1x1` to be released.
*
* Example:
* @code
* <#example#>
* @endcode
*/
void parcRingBuffer1x1_Release(PARCRingBuffer1x1 **ringPtr);
/**
* Non-blocking attempt to put item on ring. May return `false` if ring is full.
*
* @param [in,out] ring The instance of `PARCRingBuffer1x1` on which to put the @p data.
* @param [in] data The data to put on the @p ring.
*
* @return `true` Data was put on the queue
* @return `false` Would have blocked, the queue was full
*
* Example:
* @code
* <#example#>
* @endcode
*/
bool parcRingBuffer1x1_Put(PARCRingBuffer1x1 *ring, void *data);
/**
* Gets the next item off the ring, or returns false if would have blocked.
*
* Non-blocking, gets an item off the ring, or returns false if would block
*
* @param [in] ring The ring buffer
* @param [out] outputDataPtr The output pointer
*
* @return true Data returned in the output argument
* @return false Ring is empty, no data returned.
*
* Example:
* @code
* <#example#>
* @endcode
*/
bool parcRingBuffer1x1_Get(PARCRingBuffer1x1 *ring, void **outputDataPtr);
/**
* Returns the remaining capacity of the ring
*
* Returns the remaining capacity of the ring. This does not guarantee the next
* Put will not block, as other producers might consumer the space between calls.
*
* @param [in] ring The instance of `PARCRingBuffer1x1` .
*
* @return The remaining capacity on the ring.
*
* Example:
* @code
* <#example#>
* @endcode
*/
uint32_t parcRingBuffer1x1_Remaining(PARCRingBuffer1x1 *ring);
#endif // libparc_parc_RingBuffer_1x1_h
|
