Tue, 04 Oct 2022 19:25:07 +0200
fix over-optimization of strstr
1. it's actually less performant to frequently read bytes
from an array instead of using the native word length
2. the SBO buffer should be local and not static to allow
multi-threading usage
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
1 | /* |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
3 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
4 | * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
5 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
6 | * Redistribution and use in source and binary forms, with or without |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
7 | * modification, are permitted provided that the following conditions are met: |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
8 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
9 | * 1. Redistributions of source code must retain the above copyright |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
10 | * notice, this list of conditions and the following disclaimer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
11 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
12 | * 2. Redistributions in binary form must reproduce the above copyright |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
13 | * notice, this list of conditions and the following disclaimer in the |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
14 | * documentation and/or other materials provided with the distribution. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
15 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
26 | * POSSIBILITY OF SUCH DAMAGE. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
27 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
28 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
29 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
30 | * \file buffer.h |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
31 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
32 | * \brief Advanced buffer implementation. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
33 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
34 | * Instances of CxBuffer can be used to read from or to write to like one |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
35 | * would do with a stream. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
36 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
37 | * Some features for convenient use of the buffer |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
38 | * can be enabled. See the documentation of the macro constants for more |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
39 | * information. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
40 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
41 | * \author Mike Becker |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
42 | * \author Olaf Wintermann |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
43 | * \version 3.0 |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
44 | * \copyright 2-Clause BSD License |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
45 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
46 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
47 | #ifndef UCX_BUFFER_H |
484
9e6900b1cf9d
add common.h include to all other header files
Mike Becker <universe@uap-core.de>
parents:
483
diff
changeset
|
48 | #define UCX_BUFFER_H |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
49 | |
484
9e6900b1cf9d
add common.h include to all other header files
Mike Becker <universe@uap-core.de>
parents:
483
diff
changeset
|
50 | #include "common.h" |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
51 | #include "allocator.h" |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
52 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
53 | #ifdef __cplusplus |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
54 | extern "C" { |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
55 | #endif |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
56 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
57 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
58 | * No buffer features enabled (all flags cleared). |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
59 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
60 | #define CX_BUFFER_DEFAULT 0x00 |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
61 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
62 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
63 | * If this flag is enabled, the buffer will automatically free its contents when destroyed. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
64 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
65 | #define CX_BUFFER_FREE_CONTENTS 0x01 |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
66 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
67 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
68 | * If this flag is enabled, the buffer will automatically extends its capacity. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
69 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
70 | #define CX_BUFFER_AUTO_EXTEND 0x02 |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
71 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
72 | /** Structure for the UCX buffer data. */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
73 | typedef struct { |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
74 | /** A pointer to the buffer contents. */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
75 | union { |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
76 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
77 | * Data is interpreted as text. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
78 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
79 | char *space; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
80 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
81 | * Data is interpreted as binary. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
82 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
83 | unsigned char *bytes; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
84 | }; |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
85 | /** The allocator to use for automatic memory management. */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
86 | CxAllocator const *allocator; |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
87 | /** Current position of the buffer. */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
88 | size_t pos; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
89 | /** Current capacity (i.e. maximum size) of the buffer. */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
90 | size_t capacity; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
91 | /** Current size of the buffer content. */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
92 | size_t size; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
93 | /** |
539
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
94 | * The buffer may not extend beyond this threshold before starting to flush. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
95 | * Default is \c SIZE_MAX (flushing disabled when auto extension is enabled). |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
96 | */ |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
97 | size_t flush_threshold; |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
98 | /** |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
99 | * The block size for the elements to flush. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
100 | * Default is 4096 bytes. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
101 | */ |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
102 | size_t flush_blksize; |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
103 | /** |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
104 | * The maximum number of blocks to flush in one cycle. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
105 | * Zero disables flushing entirely (this is the default). |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
106 | * Set this to \c SIZE_MAX to flush the entire buffer. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
107 | * |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
108 | * @attention if the maximum number of blocks multiplied with the block size |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
109 | * is smaller than the expected contents written to this buffer within one write |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
110 | * operation, multiple flush cycles are performed after that write. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
111 | * That means the total number of blocks flushed after one write to this buffer may |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
112 | * be larger than \c flush_blkmax. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
113 | */ |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
114 | size_t flush_blkmax; |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
115 | |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
116 | /** |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
117 | * The write function used for flushing. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
118 | * If NULL, the flushed content gets discarded. |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
119 | */ |
545
3700ac4bd9a3
#184 #170 first basic flush test
Mike Becker <universe@uap-core.de>
parents:
541
diff
changeset
|
120 | cx_write_func flush_func; |
539
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
121 | |
9cd98da9ee17
#184 start implementation of the flush feature
Mike Becker <universe@uap-core.de>
parents:
537
diff
changeset
|
122 | /** |
541
67e078518935
#170 complete write tests for status quo
Mike Becker <universe@uap-core.de>
parents:
539
diff
changeset
|
123 | * The target for \c flush_func. |
67e078518935
#170 complete write tests for status quo
Mike Becker <universe@uap-core.de>
parents:
539
diff
changeset
|
124 | */ |
67e078518935
#170 complete write tests for status quo
Mike Becker <universe@uap-core.de>
parents:
539
diff
changeset
|
125 | void *flush_target; |
67e078518935
#170 complete write tests for status quo
Mike Becker <universe@uap-core.de>
parents:
539
diff
changeset
|
126 | |
67e078518935
#170 complete write tests for status quo
Mike Becker <universe@uap-core.de>
parents:
539
diff
changeset
|
127 | /** |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
128 | * Flag register for buffer features. |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
129 | * @see #CX_BUFFER_DEFAULT |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
130 | * @see #CX_BUFFER_FREE_CONTENTS |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
131 | * @see #CX_BUFFER_AUTO_EXTEND |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
132 | */ |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
133 | int flags; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
134 | } cx_buffer_s; |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
135 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
136 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
137 | * UCX buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
138 | */ |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
139 | typedef cx_buffer_s CxBuffer; |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
140 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
141 | /** |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
142 | * Initializes a fresh buffer. |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
143 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
144 | * \note You may provide \c NULL as argument for \p space. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
145 | * Then this function will allocate the space and enforce |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
146 | * the #CX_BUFFER_FREE_CONTENTS flag. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
147 | * |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
148 | * @param buffer the buffer to initialize |
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
149 | * @param space pointer to the memory area, or \c NULL to allocate |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
150 | * new memory |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
151 | * @param capacity the capacity of the buffer |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
152 | * @param allocator the allocator this buffer shall use for automatic memory management |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
153 | * @param flags buffer features (see cx_buffer_s.flags) |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
154 | * @return zero on success, non-zero if a required allocation failed |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
155 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
156 | __attribute__((__nonnull__(1, 4))) |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
157 | int cxBufferInit( |
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
158 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
159 | void *space, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
160 | size_t capacity, |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
161 | CxAllocator const *allocator, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
162 | int flags |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
163 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
164 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
165 | /** |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
166 | * Destroys the buffer contents. |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
167 | * |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
168 | * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled. |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
169 | * |
501
9a08f5e515cc
add allocator support to CxBuffer
Mike Becker <universe@uap-core.de>
parents:
500
diff
changeset
|
170 | * @param buffer the buffer which contents shall be destroyed |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
171 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
172 | __attribute__((__nonnull__)) |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
173 | void cxBufferDestroy(CxBuffer *buffer); |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
174 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
175 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
176 | * Shifts the contents of the buffer by the given offset. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
177 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
178 | * If the offset is positive, the contents are shifted to the right. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
179 | * If auto extension is enabled, the buffer grows, if necessary. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
180 | * In case the auto extension fails, this function returns a non-zero value and |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
181 | * no contents are changed. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
182 | * If auto extension is disabled, the contents that do not fit into the buffer |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
183 | * are discarded. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
184 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
185 | * If the offset is negative, the contents are shifted to the left where the |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
186 | * first \p shift bytes are discarded. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
187 | * The new size of the buffer is the old size minus the absolute shift value. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
188 | * If this value is larger than the buffer size, the buffer is emptied (but |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
189 | * not cleared, see the security note below). |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
190 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
191 | * The buffer position gets shifted alongside with the content but is kept |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
192 | * within the boundaries of the buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
193 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
194 | * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
195 | * cxBufferShiftRight() functions using a \c size_t as parameter type. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
196 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
197 | * \attention |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
198 | * Security Note: The shifting operation does \em not erase the previously occupied memory cells. |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
199 | * But you can easily do that manually, e.g. by calling |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
200 | * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or |
531
1b8624c8448e
fix erroneous doc for cxBufferShift
Mike Becker <universe@uap-core.de>
parents:
530
diff
changeset
|
201 | * <code>memset(buffer->bytes + buffer->size, 0, buffer->capacity - buffer->size)</code> |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
202 | * for a left shift. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
203 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
204 | * @param buffer the buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
205 | * @param shift the shift offset (negative means left shift) |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
206 | * @return 0 on success, non-zero if a required auto-extension fails |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
207 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
208 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
209 | int cxBufferShift( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
210 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
211 | off_t shift |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
212 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
213 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
214 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
215 | * Shifts the buffer to the right. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
216 | * See cxBufferShift() for details. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
217 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
218 | * @param buffer the buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
219 | * @param shift the shift offset |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
220 | * @return 0 on success, non-zero if a required auto-extension fails |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
221 | * @see cxBufferShift() |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
222 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
223 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
224 | int cxBufferShiftRight( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
225 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
226 | size_t shift |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
227 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
228 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
229 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
230 | * Shifts the buffer to the left. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
231 | * See cxBufferShift() for details. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
232 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
233 | * \note Since a left shift cannot fail due to memory allocation problems, this |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
234 | * function always returns zero. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
235 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
236 | * @param buffer the buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
237 | * @param shift the positive shift offset |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
238 | * @return always zero |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
239 | * @see cxBufferShift() |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
240 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
241 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
242 | int cxBufferShiftLeft( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
243 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
244 | size_t shift |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
245 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
246 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
247 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
248 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
249 | * Moves the position of the buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
250 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
251 | * The new position is relative to the \p whence argument. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
252 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
253 | * \li \c SEEK_SET marks the start of the buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
254 | * \li \c SEEK_CUR marks the current position. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
255 | * \li \c SEEK_END marks the end of the buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
256 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
257 | * With an offset of zero, this function sets the buffer position to zero |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
258 | * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
259 | * unchanged (\c SEEK_CUR). |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
260 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
261 | * @param buffer the buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
262 | * @param offset position offset relative to \p whence |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
263 | * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
264 | * @return 0 on success, non-zero if the position is invalid |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
265 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
266 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
267 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
268 | int cxBufferSeek( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
269 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
270 | off_t offset, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
271 | int whence |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
272 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
273 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
274 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
275 | * Clears the buffer by resetting the position and deleting the data. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
276 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
277 | * The data is deleted by zeroing it with a call to memset(). |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
278 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
279 | * @param buffer the buffer to be cleared |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
280 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
281 | __attribute__((__nonnull__)) |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
282 | void cxBufferClear(CxBuffer *buffer); |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
283 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
284 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
285 | * Tests, if the buffer position has exceeded the buffer capacity. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
286 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
287 | * @param buffer the buffer to test |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
288 | * @return non-zero, if the current buffer position has exceeded the last |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
289 | * available byte of the buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
290 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
291 | __attribute__((__nonnull__)) |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
292 | int cxBufferEof(CxBuffer const *buffer); |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
293 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
294 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
295 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
296 | * Ensures that the buffer has a minimum capacity. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
297 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
298 | * If the current capacity is not sufficient, the buffer will be extended. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
299 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
300 | * @param buffer the buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
301 | * @param capacity the minimum required capacity for this buffer |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
302 | * @return 0 on success or a non-zero value on failure |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
303 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
304 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
305 | int cxBufferMinimumCapacity( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
306 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
307 | size_t capacity |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
308 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
309 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
310 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
311 | * Writes data to a CxBuffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
312 | * |
567
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
313 | * If flushing is enabled and the buffer needs to flush, the data is flushed to |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
314 | * the target until the target signals that it cannot take more data by |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
315 | * returning zero via the respective write function. In that case, the remaining |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
316 | * data in this buffer is shifted to the beginning of this buffer so that the |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
317 | * newly available space can be used to append as much data as possible. This |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
318 | * function only stops writing more elements, when the flush target and this |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
319 | * buffer are both incapable of taking more data or all data has been written. |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
320 | * The number returned by this function is the total number of elements that |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
321 | * could be written during the process. It does not necessarily mean that those |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
322 | * elements are still in this buffer, because some of them could have also be |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
323 | * flushed already. |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
324 | * |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
325 | * If automatic flushing is not enabled, the position of the buffer is increased |
f90a7cfe2480
#184 #170 more thorough flush testing
Mike Becker <universe@uap-core.de>
parents:
545
diff
changeset
|
326 | * by the number of bytes written. |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
327 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
328 | * \note The signature is compatible with the fwrite() family of functions. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
329 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
330 | * @param ptr a pointer to the memory area containing the bytes to be written |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
331 | * @param size the length of one element |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
332 | * @param nitems the element count |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
333 | * @param buffer the CxBuffer to write to |
537
16219eba3a0a
fix doc error for cxBufferWrite
Mike Becker <universe@uap-core.de>
parents:
531
diff
changeset
|
334 | * @return the total count of elements written |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
335 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
336 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
337 | size_t cxBufferWrite( |
489
af6be1e123aa
add some const qualifiers
Mike Becker <universe@uap-core.de>
parents:
485
diff
changeset
|
338 | void const *ptr, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
339 | size_t size, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
340 | size_t nitems, |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
341 | CxBuffer *buffer |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
342 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
343 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
344 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
345 | * Reads data from a CxBuffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
346 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
347 | * The position of the buffer is increased by the number of bytes read. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
348 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
349 | * \note The signature is compatible with the fread() family of functions. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
350 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
351 | * @param ptr a pointer to the memory area where to store the read data |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
352 | * @param size the length of one element |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
353 | * @param nitems the element count |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
354 | * @param buffer the CxBuffer to read from |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
355 | * @return the total number of elements read |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
356 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
357 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
358 | size_t cxBufferRead( |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
359 | void *ptr, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
360 | size_t size, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
361 | size_t nitems, |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
362 | CxBuffer *buffer |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
363 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
364 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
365 | /** |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
366 | * Writes a character to a buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
367 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
368 | * The least significant byte of the argument is written to the buffer. If the |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
369 | * end of the buffer is reached and #CX_BUFFER_AUTO_EXTEND feature is enabled, |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
370 | * the buffer capacity is extended by cxBufferMinimumCapacity(). If the feature is |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
371 | * disabled or buffer extension fails, \c EOF is returned. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
372 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
373 | * On successful write, the position of the buffer is increased. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
374 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
375 | * @param buffer the buffer to write to |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
376 | * @param c the character to write |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
377 | * @return the byte that has bean written or \c EOF when the end of the stream is |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
378 | * reached and automatic extension is not enabled or not possible |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
379 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
380 | __attribute__((__nonnull__)) |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
381 | int cxBufferPut( |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
382 | CxBuffer *buffer, |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
383 | int c |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
384 | ); |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
385 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
386 | /** |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
387 | * Writes a string to a buffer. |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
388 | * |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
389 | * @param buffer the buffer |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
390 | * @param str the zero-terminated string |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
391 | * @return the number of bytes written |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
392 | */ |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
393 | __attribute__((__nonnull__)) |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
394 | size_t cxBufferPutString( |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
395 | CxBuffer *buffer, |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
396 | const char *str |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
397 | ); |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
398 | |
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
399 | /** |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
400 | * Gets a character from a buffer. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
401 | * |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
402 | * The current position of the buffer is increased after a successful read. |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
403 | * |
485
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
404 | * @param buffer the buffer to read from |
6a86ad3d8c03
use same doxygen style in all files
Mike Becker <universe@uap-core.de>
parents:
484
diff
changeset
|
405 | * @return the character or \c EOF, if the end of the buffer is reached |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
406 | */ |
529
814d51173f20
#171 const qualifier and nonnull attributes
Mike Becker <universe@uap-core.de>
parents:
501
diff
changeset
|
407 | __attribute__((__nonnull__)) |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
489
diff
changeset
|
408 | int cxBufferGet(CxBuffer *buffer); |
483
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
409 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
410 | #ifdef __cplusplus |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
411 | } |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
412 | #endif |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
413 | |
929016224c3c
add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
414 | #endif /* UCX_BUFFER_H */ |