comparison: ucx/buffer.h
ucx/buffer.h
- changeset 124
- 80609f9675f1
- parent 0
- 1f419bd32da1
- child 152
- 62921b370c60
equal
deleted
inserted
replaced
| 123:55adc92e7c09 | 124:80609f9675f1 |
|---|---|
| 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 /** |
