From 63557623eba8b58076e0454731a2d52e2ac5966b Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Sat, 27 May 2017 07:32:50 -0400 Subject: [PATCH] Docs: improve the documentation of the dynamic buffer interface MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérémie Galarneau --- src/common/dynamic-buffer.c | 18 +++++++++--------- src/common/dynamic-buffer.h | 36 ++++++++++++++++++++++++++++++++---- 2 files changed, 41 insertions(+), 13 deletions(-) diff --git a/src/common/dynamic-buffer.c b/src/common/dynamic-buffer.c index 05d3022af..4f1116213 100644 --- a/src/common/dynamic-buffer.c +++ b/src/common/dynamic-buffer.c @@ -59,11 +59,11 @@ int lttng_dynamic_buffer_append(struct lttng_dynamic_buffer *buffer, goto end; } - assert(buffer->capacity >= buffer->size); - if (buffer->capacity < (len + buffer->size)) { + assert(buffer->_capacity >= buffer->size); + if (buffer->_capacity < (len + buffer->size)) { ret = lttng_dynamic_buffer_set_capacity(buffer, - buffer->capacity + - (len - (buffer->capacity - buffer->size))); + buffer->_capacity + + (len - (buffer->_capacity - buffer->size))); if (ret) { goto end; } @@ -104,9 +104,9 @@ int lttng_dynamic_buffer_set_size(struct lttng_dynamic_buffer *buffer, goto end; } - if (new_size > buffer->capacity) { + if (new_size > buffer->_capacity) { size_t original_size = buffer->size; - size_t original_capacity = buffer->capacity; + size_t original_capacity = buffer->_capacity; ret = lttng_dynamic_buffer_set_capacity(buffer, new_size); if (ret) { @@ -155,7 +155,7 @@ int lttng_dynamic_buffer_set_capacity(struct lttng_dynamic_buffer *buffer, goto end; } - if (new_capacity == buffer->capacity) { + if (new_capacity == buffer->_capacity) { goto end; } @@ -166,7 +166,7 @@ int lttng_dynamic_buffer_set_capacity(struct lttng_dynamic_buffer *buffer, goto end; } buffer->data = new_buf; - buffer->capacity = new_capacity; + buffer->_capacity = new_capacity; end: return ret; } @@ -178,6 +178,6 @@ void lttng_dynamic_buffer_reset(struct lttng_dynamic_buffer *buffer) return; } buffer->size = 0; - buffer->capacity = 0; + buffer->_capacity = 0; free(buffer->data); } diff --git a/src/common/dynamic-buffer.h b/src/common/dynamic-buffer.h index 19097f927..d05356b73 100644 --- a/src/common/dynamic-buffer.h +++ b/src/common/dynamic-buffer.h @@ -23,33 +23,61 @@ struct lttng_dynamic_buffer { char *data; + /* size is the buffer's currently used capacity. */ size_t size; - size_t capacity; + /* + * capacity shall not be accessed by users directly, it is meant for + * internal use only. + */ + size_t _capacity; }; +/* + * Initialize a dynamic buffer. This performs no allocation and is meant + * to be used instead of memset or explicit initialization of the buffer. + */ void lttng_dynamic_buffer_init(struct lttng_dynamic_buffer *buffer); +/* + * Append the content of a raw memory buffer to the end of a dynamic buffer + * (after its current "size"). The dynamic buffer's size is increased by + * "len", and its capacity is adjusted automatically. + */ int lttng_dynamic_buffer_append(struct lttng_dynamic_buffer *buffer, const void *buf, size_t len); +/* + * Performs the same action as lttng_dynamic_buffer_append(), but using another + * dynamic buffer as the source buffer. The source buffer's size is used in lieu + * of "len". + */ int lttng_dynamic_buffer_append_buffer(struct lttng_dynamic_buffer *dst_buffer, struct lttng_dynamic_buffer *src_buffer); /* * Set the buffer's size to new_size. The capacity of the buffer will * be expanded (if necessary) to accomodate new_size. Areas acquired by - * an enlarging new_size _will be zeroed_. + * a size increase will be zeroed. * * Be careful to expand the buffer's size _before_ calling out external * APIs (e.g. read(3)) which may populate the buffer as setting the size - * _after_ will zero-out the result of the operation. + * after will zero-out the result of the operation. + * + * Shrinking a buffer does not zero the old content. If the buffer may contain + * sensititve information, it must be cleared manually _before_ changing the + * size. + * + * NOTE: It is striclty _invalid_ to access memory after _size_, regardless + * of prior calls to set_capacity(). */ int lttng_dynamic_buffer_set_size(struct lttng_dynamic_buffer *buffer, size_t new_size); /* * Set the buffer's capacity to accomodate the new_capacity, allocating memory - * as necessary. The buffer's content is preserved. + * as necessary. The buffer's content is preserved. Setting a buffer's capacity + * is meant as a _hint_ to the underlying buffer and is only optimization; no + * guarantee is offered that subsequent calls to append or set_size will succeed. * * If the current size > new_capacity, the operation will fail. */ -- 2.34.1