From: James Jones Date: Tue, 26 Jan 2021 20:52:42 +0000 (-0600) Subject: Remove FR_DBUFF_RESERVE*() now that nothing uses it. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=789466ac89064fc243f3b17caaa6055f4654bc17;p=thirdparty%2Ffreeradius-server.git Remove FR_DBUFF_RESERVE*() now that nothing uses it. This allows a simpler, more direct expression of FR_DBUFF_MAX*() (for now, at least; things will get interesting again when we let FR_DBUFF_MAX*() take advantage of extensibility) --- diff --git a/doc/antora/modules/developers/pages/dbuff.adoc b/doc/antora/modules/developers/pages/dbuff.adoc index f05dc5c102..360ae8a55b 100644 --- a/doc/antora/modules/developers/pages/dbuff.adoc +++ b/doc/antora/modules/developers/pages/dbuff.adoc @@ -85,7 +85,7 @@ Here are the things one can do with a dbuff: decoding - read data from the next available byte or bytes. * Explicitly move the "next byte" pointer either ahead by a number of bytes, to the start, or to the end. * Ask how the dbuff how many bytes are remaining or have been used. - + When encoding, data can either be one or more bytes or a signed or unsigned 8, 16, 32, or 64 bit integer. There is also a `memset()` function for initialising uninitialised areas of the buffer. As @@ -113,23 +113,19 @@ will allow reading or writing outside of the buffer. A child dbuff operates on a portion of the buffer, starting where the parent left off. The creator can control two things about the child: -* The space available to the child. There are two ways to specify this: -** Give the child no more than a specified number of bytes (`FR_DBUFF_MAX()`). -** Insist that the child only be given enough bytes that the parent has a certain number (`FR_DBUFF_RESERVE()`). +* The space available to the child (`FR_DBUFF_MAX()` gives a child + dbuff with no more than a specified number of bytes available). * Whether the child's advances propagate up to its parents (`FR_DBUFF_NO_ADVANCE()` gives a child dbuff whose advances don't - propagate, and `FR_DBUFF_RESERVE_NO_ADVANCE()` lets you reserve and - prevent propagation). - -[IMPORTANT] -==== -`FR_DBUFF_MAX()` cannott fail, It is like an ad promising "up to one -million dollars!" where "up to" includes zero. `FR_DBUFF_RESERVE()`, -though, can fail in a sense, because you're promising the parent at -least a certain number of bytes. Underneath they're both C compound -literals, so it's not clear how to indicate an error. + propagate). + +[IMPORTANT] ==== - +`FR_DBUFF_MAX()` cannot fail. It is like an ad promising "up to one +million dollars!" where "up to" includes zero, so the child may have +less space than the specified maximum. +==== + `FR_DBUFF_MAX()` typically shows up when a caller limits a callee to what will fit in a TLV in some context. `FR_DBUFF_NO_ADVANCE()` came into existence to let an encoding function write a header and then @@ -142,9 +138,9 @@ become a convention: ssize_t encode_foo(fr_dbuff_t *dbuff, ...) { fr_dbuff_t work_dbuff = FR_DBUFF_NO_ADVANCE(dbuff); - + /* encode, operating on work_dbuff, returning on error */ - + return fr_dbuff_advance(dbuff, fr_dbuff_used(&work_dbuff)); } ---- @@ -175,6 +171,6 @@ instead of [source,c] ---- f ((val = fr_dbuff_foo(dbuff, ...) < 0) return val; ----- - +---- + letting one return an error to the caller without cluttering the code. diff --git a/src/lib/util/dbuff.h b/src/lib/util/dbuff.h index d0eb945959..10f202057d 100644 --- a/src/lib/util/dbuff.h +++ b/src/lib/util/dbuff.h @@ -227,17 +227,15 @@ do { \ /** @cond */ -/** Reserve _reserve bytes in the dbuff when passing it to another function +/** Limit available bytes in the dbufft to _max when passing it to another function * * @private */ -#define _FR_DBUFF_RESERVE(_dbuff, _reserve, _adv_parent) \ +#define _FR_DBUFF_MAX(_dbuff, _max, _adv_parent) \ (fr_dbuff_t){ \ .buff = (_dbuff)->buff, \ .start = (_dbuff)->p, \ - .end = ((_dbuff)->end - (_reserve)) >= ((_dbuff)->p) ? \ - (_dbuff)->end - (_reserve) : \ - (_dbuff)->p, \ + .end = (((((_dbuff)->end) - (_max) < (_dbuff)->p)) ? (_dbuff)->end : ((_dbuff)->p + (_max))), \ .p = (_dbuff)->p, \ .is_const = (_dbuff)->is_const, \ .adv_parent = _adv_parent, \ @@ -248,44 +246,6 @@ do { \ } /* @endcond */ -/** Reserve _reserve bytes in the dbuff when passing it to another function - * - @code{.c} - my_child_encoder(&FR_DBUFF_RESERVE(dbuff, 5), vp); - @endcode - * - * @note Do not use to re-initialise the contents of _dbuff, i.e. to - * permanently shrink the exiting dbuff. The parent pointer will loop. - * - * @note Do not modify the "child" dbuff directly. Use the functions - * supplied as part of this API. - * - * @param[in] _dbuff to reserve bytes in. - * @param[in] _reserve The number of bytes to reserve. - */ -#define FR_DBUFF_RESERVE(_dbuff, _reserve) _FR_DBUFF_RESERVE(_dbuff, _reserve, true) - -/** Reserve _reserve bytes in the dbuff when passing it to another function - * - @code{.c} - fr_dbuff_t tlv = FR_DBUFF_RESERVE_NO_ADVANCE(dbuff, UINT8_MAX); - - if (my_child_encoder(&tlv, vp) < 0) return -1; - - return fr_dbuff_advance(dbuff, fr_dbuff_used(tlv)); - @endcode - * - * @note Do not use to re-initialise the contents of _dbuff, i.e. to - * permanently shrink the exiting dbuff. The parent pointer will loop. - * - * @note Do not modify the "child" dbuff directly. Use the functions - * supplied as part of this API. - * - * @param[in] _dbuff to reserve bytes in. - * @param[in] _reserve The number of bytes to reserve. - */ -#define FR_DBUFF_RESERVE_NO_ADVANCE(_dbuff, _reserve) _FR_DBUFF_RESERVE(_dbuff, _reserve, false) - /** Limit the maximum number of bytes available in the dbuff when passing it to another function * @code{.c} @@ -301,8 +261,7 @@ do { \ * @param[in] _dbuff to reserve bytes in. * @param[in] _max The maximum number of bytes the caller is allowed to write to. */ -#define FR_DBUFF_MAX(_dbuff, _max) \ - _FR_DBUFF_RESERVE(_dbuff, (fr_dbuff_remaining(_dbuff) > (_max)) ? (fr_dbuff_remaining(_dbuff) - (_max)) : 0, true) +#define FR_DBUFF_MAX(_dbuff, _max) _FR_DBUFF_MAX(_dbuff, _max, true) /** Limit the maximum number of bytes available in the dbuff when passing it to another function * @@ -323,8 +282,7 @@ do { \ * @param[in] _dbuff to reserve bytes in. * @param[in] _max The maximum number of bytes the caller is allowed to write to. */ -#define FR_DBUFF_MAX_NO_ADVANCE(_dbuff, _max) \ - _FR_DBUFF_RESERVE(_dbuff, (fr_dbuff_remaining(_dbuff) > (_max)) ? (fr_dbuff_remaining(_dbuff) - (_max)) : 0, false) +#define FR_DBUFF_MAX_NO_ADVANCE(_dbuff, _max) _FR_DBUFF_MAX(_dbuff, _max, false) /** Does the actual work of initialising a dbuff * @private