From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp60.i.mail.ru (smtp60.i.mail.ru [217.69.128.40]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dev.tarantool.org (Postfix) with ESMTPS id 37FA1446439 for ; Thu, 22 Oct 2020 13:20:59 +0300 (MSK) From: Timur Safin Date: Thu, 22 Oct 2020 13:20:40 +0300 Message-Id: <213dd4ecad3e83c9d1ef3821e38b5584b0636c66.1603360022.git.tsafin@tarantool.org> In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [Tarantool-patches] [PATCH 1/2] module api: proper documentation for the ibuf wrapper List-Id: Tarantool development patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: v.shpilevoy@tarantool.org, alexander.turenko@tarantool.org Cc: tarantool-patches@dev.tarantool.org We have extended module api as part of #5384 but there were some complains that this part ofapi is not self-contained and it's impossible to understand what's going on there without looking into small/ibuf.[hc] sources. Now we try to document the essential part of ibuf structure so API should makes much more sense now. Follow-up to #5384 --- src/box/ibuf.h | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/src/box/ibuf.h b/src/box/ibuf.h index 8c6d053c4..f411a13c9 100644 --- a/src/box/ibuf.h +++ b/src/box/ibuf.h @@ -40,19 +40,42 @@ extern "C" { /** \cond public */ +/** + * "@p box_ibuf_t is an opaque alias for struct @p ibuf + * defined in the small library. + * + * The structure is a buffer composing of several pointers and + * counters, which serve purpose of keeping 2 joint areas + * in buffer: + * - useful area [rpos, wpos) + * - and one, which is unused yet [wpos, end) + * + * +---+--------+---------+ + * buf -> | |..used..|.unused..| + * +---+--------+---------+ + * ^ ^ ^ + * rpos wpos end + * + */ typedef struct ibuf box_ibuf_t; /** - * Reserve requested amount of bytes in ibuf buffer + * Reserve requested amount of bytes in ibuf buffer. + * * @param ibuf buffer used for allocation * @param size allocated bytes + * * @retval NULL on error, check diag. */ API_EXPORT void * box_ibuf_reserve(box_ibuf_t *ibuf, size_t size); /** - * Return pointers to read range pointers used [rpos..wpos) + * Return pointers to read range pointers used [rpos..wpos). + * + * All arguments should be non-NULL, with exception of last one + * @p wpos which is optional and allows NULL. + * * @param ibuf ibuf structure * @param rpos where to place ibuf.rpos address * @param wpos where to place ibuf.wpos address @@ -61,7 +84,11 @@ API_EXPORT void box_ibuf_read_range(box_ibuf_t *ibuf, char ***rpos, char ***wpos); /** - * Return pointers to write range pointers used [wpos..end) + * Return pointers to write range pointers used [wpos..end). + * + * All arguments should be non-NULL, with exception of last one + * @p end which is optional and allows NULL. + * * @param ibuf ibuf structure * @param wpos where to place ibuf.rpos address * @param end where to place ibuf.wpos address -- 2.20.1