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
|
#ifndef AWS_COMMON_RING_BUFFER_H
#define AWS_COMMON_RING_BUFFER_H
/**
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0.
*/
#include <aws/common/atomics.h>
AWS_PUSH_SANE_WARNING_LEVEL
/**
* Lockless ring buffer implementation that is thread safe assuming a single thread acquires and a single thread
* releases. For any other use case (other than the single-threaded use-case), you must manage thread-safety manually.
*
* Also, a very important note: release must happen in the same order as acquire. If you do not your application, and
* possibly computers within a thousand mile radius, may die terrible deaths, and the local drinking water will be
* poisoned for generations with fragments of what is left of your radioactive corrupted memory.
*/
struct aws_ring_buffer {
struct aws_allocator *allocator;
uint8_t *allocation;
struct aws_atomic_var head;
struct aws_atomic_var tail;
uint8_t *allocation_end;
};
struct aws_byte_buf;
AWS_EXTERN_C_BEGIN
/**
* Initializes a ring buffer with an allocation of size `size`. Returns AWS_OP_SUCCESS on a successful initialization,
* AWS_OP_ERR otherwise.
*/
AWS_COMMON_API int aws_ring_buffer_init(struct aws_ring_buffer *ring_buf, struct aws_allocator *allocator, size_t size);
/*
* Checks whether atomic_ptr correctly points to a memory location within the bounds of the aws_ring_buffer
*/
AWS_STATIC_IMPL bool aws_ring_buffer_check_atomic_ptr(
const struct aws_ring_buffer *ring_buf,
const uint8_t *atomic_ptr);
/**
* Checks whether the ring buffer is empty
*/
AWS_STATIC_IMPL bool aws_ring_buffer_is_empty(const struct aws_ring_buffer *ring_buf);
/**
* Evaluates the set of properties that define the shape of all valid aws_ring_buffer structures.
* It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).
*/
AWS_STATIC_IMPL bool aws_ring_buffer_is_valid(const struct aws_ring_buffer *ring_buf);
/**
* Cleans up the ring buffer's resources.
*/
AWS_COMMON_API void aws_ring_buffer_clean_up(struct aws_ring_buffer *ring_buf);
/**
* Attempts to acquire `requested_size` buffer and stores the result in `dest` if successful. Returns AWS_OP_SUCCESS if
* the requested size was available for use, AWS_OP_ERR otherwise.
*/
AWS_COMMON_API int aws_ring_buffer_acquire(
struct aws_ring_buffer *ring_buf,
size_t requested_size,
struct aws_byte_buf *dest);
/**
* Attempts to acquire `requested_size` buffer and stores the result in `dest` if successful. If not available, it will
* attempt to acquire anywhere from 1 byte to `requested_size`. Returns AWS_OP_SUCCESS if some buffer space is available
* for use, AWS_OP_ERR otherwise.
*/
AWS_COMMON_API int aws_ring_buffer_acquire_up_to(
struct aws_ring_buffer *ring_buf,
size_t minimum_size,
size_t requested_size,
struct aws_byte_buf *dest);
/**
* Releases `buf` back to the ring buffer for further use. RELEASE MUST HAPPEN in the SAME ORDER AS ACQUIRE.
* If you do not, your application, and possibly computers within a thousand mile radius, may die terrible deaths,
* and the local drinking water will be poisoned for generations
* with fragments of what is left of your radioactive corrupted memory.
*/
AWS_COMMON_API void aws_ring_buffer_release(struct aws_ring_buffer *ring_buffer, struct aws_byte_buf *buf);
/**
* Returns true if the memory in `buf` was vended by this ring buffer, false otherwise.
* Make sure `buf->buffer` and `ring_buffer->allocation` refer to the same memory region.
*/
AWS_COMMON_API bool aws_ring_buffer_buf_belongs_to_pool(
const struct aws_ring_buffer *ring_buffer,
const struct aws_byte_buf *buf);
#ifndef AWS_NO_STATIC_IMPL
# include <aws/common/ring_buffer.inl>
#endif /* AWS_NO_STATIC_IMPL */
AWS_EXTERN_C_END
AWS_POP_SANE_WARNING_LEVEL
#endif /* AWS_COMMON_RING_BUFFER_H */
|
