1 /* |
1 /* |
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
3 * |
3 * |
4 * Copyright 2013 Olaf Wintermann. All rights reserved. |
4 * Copyright 2015 Olaf Wintermann. All rights reserved. |
5 * |
5 * |
6 * Redistribution and use in source and binary forms, with or without |
6 * Redistribution and use in source and binary forms, with or without |
7 * modification, are permitted provided that the following conditions are met: |
7 * modification, are permitted provided that the following conditions are met: |
8 * |
8 * |
9 * 1. Redistributions of source code must retain the above copyright |
9 * 1. Redistributions of source code must retain the above copyright |
95 * <code>space</code>. Then this function will allocate the space and enforce |
95 * <code>space</code>. Then this function will allocate the space and enforce |
96 * the #UCX_BUFFER_AUTOFREE flag. |
96 * the #UCX_BUFFER_AUTOFREE flag. |
97 * |
97 * |
98 * @param space pointer to the memory area, or <code>NULL</code> to allocate |
98 * @param space pointer to the memory area, or <code>NULL</code> to allocate |
99 * new memory |
99 * new memory |
100 * @param size the size of the buffer |
100 * @param capacity the capacity of the buffer |
101 * @param flags buffer features (see UcxBuffer.flags) |
101 * @param flags buffer features (see UcxBuffer.flags) |
102 * @return the new buffer |
102 * @return the new buffer |
103 */ |
103 */ |
104 UcxBuffer *ucx_buffer_new(void *space, size_t size, int flags); |
104 UcxBuffer *ucx_buffer_new(void *space, size_t capacity, int flags); |
105 |
105 |
106 /** |
106 /** |
107 * Destroys a buffer. |
107 * Destroys a buffer. |
108 * |
108 * |
109 * If the #UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer |
109 * If the #UCX_BUFFER_AUTOFREE feature is enabled, the contents of the buffer |
118 * |
118 * |
119 * <b>Note:</b> the #UCX_BUFFER_AUTOFREE feature is enforced for the new buffer. |
119 * <b>Note:</b> the #UCX_BUFFER_AUTOFREE feature is enforced for the new buffer. |
120 * |
120 * |
121 * @param src the source buffer |
121 * @param src the source buffer |
122 * @param start the start position of extraction |
122 * @param start the start position of extraction |
123 * @param length the count of bytes to extract or 0 if all of the remaining |
123 * @param length the count of bytes to extract (must not be zero) |
124 * bytes shall be extracted |
|
125 * @param flags feature mask for the new buffer |
124 * @param flags feature mask for the new buffer |
126 * @return |
125 * @return a new buffer containing the extraction |
127 */ |
126 */ |
128 UcxBuffer* ucx_buffer_extract(UcxBuffer *src, |
127 UcxBuffer* ucx_buffer_extract(UcxBuffer *src, |
129 size_t start, size_t length, int flags); |
128 size_t start, size_t length, int flags); |
130 |
129 |
131 /** |
130 /** |
134 * @param src the source buffer |
133 * @param src the source buffer |
135 * @param flags feature mask for the new buffer |
134 * @param flags feature mask for the new buffer |
136 * @return a new buffer with the extracted content |
135 * @return a new buffer with the extracted content |
137 */ |
136 */ |
138 #define ucx_buffer_clone(src,flags) \ |
137 #define ucx_buffer_clone(src,flags) \ |
139 ucx_buffer_extract(src, 0, 0, flags) |
138 ucx_buffer_extract(src, 0, (src)->capacity, flags) |
140 |
139 |
141 /** |
140 /** |
142 * Moves the position of the buffer. |
141 * Moves the position of the buffer. |
143 * |
142 * |
144 * The new position is relative to the <code>whence</code> argument. |
143 * The new position is relative to the <code>whence</code> argument. |
145 * |
144 * |
146 * SEEK_SET marks the start of the buffer. |
145 * SEEK_SET marks the start of the buffer. |
147 * SEEK_CUR marks the current position. |
146 * SEEK_CUR marks the current position. |
148 * SEEK_END marks the first 0-byte in the buffer. |
147 * SEEK_END marks the end of the buffer. |
|
148 * |
|
149 * With an offset of zero, this function sets the buffer position to zero |
|
150 * (SEEK_SET), the buffer size (SEEK_END) or leaves the buffer position |
|
151 * unchanged (SEEK_CUR). |
149 * |
152 * |
150 * @param buffer |
153 * @param buffer |
151 * @param offset position offset relative to <code>whence</code> |
154 * @param offset position offset relative to <code>whence</code> |
152 * @param whence one of SEEK_SET, SEEK_CUR or SEEK_END |
155 * @param whence one of SEEK_SET, SEEK_CUR or SEEK_END |
153 * @return 0 on success, non-zero if the position is invalid |
156 * @return 0 on success, non-zero if the position is invalid |
180 * |
183 * |
181 * <b>Note:</b> The buffer capacity increased by a power of two. I.e. |
184 * <b>Note:</b> The buffer capacity increased by a power of two. I.e. |
182 * the buffer capacity is doubled, as long as it would not hold the current |
185 * the buffer capacity is doubled, as long as it would not hold the current |
183 * content plus the additional required bytes. |
186 * content plus the additional required bytes. |
184 * |
187 * |
185 * <b>Attention:</b> the argument provided is the count of <i>additional</i> |
188 * <b>Attention:</b> the argument provided is the number of <i>additional</i> |
186 * bytes the buffer shall hold. It is <b>NOT</b> the total count of bytes the |
189 * bytes the buffer shall hold. It is <b>NOT</b> the total number of bytes the |
187 * buffer shall hold. |
190 * buffer shall hold. |
188 * |
191 * |
189 * @param buffer the buffer to extend |
192 * @param buffer the buffer to extend |
190 * @param additional_bytes the count of additional bytes the buffer shall |
193 * @param additional_bytes the number of additional bytes the buffer shall |
191 * <i>at least</i> hold |
194 * <i>at least</i> hold |
192 * @return 0 on success or a non-zero value on failure |
195 * @return 0 on success or a non-zero value on failure |
193 */ |
196 */ |
194 int ucx_buffer_extend(UcxBuffer *buffer, size_t additional_bytes); |
197 int ucx_buffer_extend(UcxBuffer *buffer, size_t additional_bytes); |
195 |
198 |
214 * |
217 * |
215 * @param ptr a pointer to the memory area where to store the read data |
218 * @param ptr a pointer to the memory area where to store the read data |
216 * @param size the length of one element |
219 * @param size the length of one element |
217 * @param nitems the element count |
220 * @param nitems the element count |
218 * @param buffer the UcxBuffer to read from |
221 * @param buffer the UcxBuffer to read from |
219 * @return the total count of bytes read |
222 * @return the total number of elements read |
220 */ |
223 */ |
221 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems, |
224 size_t ucx_buffer_read(void *ptr, size_t size, size_t nitems, |
222 UcxBuffer *buffer); |
225 UcxBuffer *buffer); |
223 |
226 |
224 /** |
227 /** |