From 66df5f3891779f8d55dd5afba1db466cea2cc2e9 Mon Sep 17 00:00:00 2001 From: Thomas Jarosch Date: Fri, 2 Jan 2015 18:41:30 +0100 Subject: Improve core_alloc() / buflib_alloc() documentation Document the fact that buffers are movable by default. Care must be taken to not pass them to functions that yield(). Also clarify other things: - Passing NULL as "ops" to buflib_alloc_ex() causes buffers to be movable by default (but not shrinkable). - If you want shrinkable buffers during compaction, you have to provide a shrink callback. - To disable buffer movement, you have to pass NULL for the move_callback inside the callback structure. - The concept of default callbacks was removed long ago, remove the only reference of it. Change-Id: I3bf0ea6b08b507d80a19f3c2c835aca32b3f7800 --- firmware/include/buflib.h | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'firmware/include') diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h index 50722bb351..7f534c6ce0 100644 --- a/firmware/include/buflib.h +++ b/firmware/include/buflib.h @@ -94,8 +94,11 @@ struct buflib_callbacks { * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_MOVE if movement * is impossible at this moment. * - * If NULL: this allocation must not be moved around by the buflib when - * compation occurs + * If NULL: this allocation must not be moved around + * by the buflib when compaction occurs. Attention: Don't confuse + * that with passing NULL for the whole callback structure + * to buflib_alloc_ex(). This would enable moving buffers by default. + * You have to pass NULL inside the "struct buflib_callbacks" structure. */ int (*move_callback)(int handle, void* current, void* new); /** @@ -193,6 +196,9 @@ bool buflib_context_relocate(struct buflib_context *ctx, void *buf); * * size: How many bytes to allocate * + * This function passes NULL for the callback structure "ops", so buffers + * are movable. Don't pass them to functions that yield(). + * * Returns: A positive integer handle identifying this allocation, or * a negative value on error (0 is also not a valid handle) */ @@ -205,7 +211,8 @@ int buflib_alloc(struct buflib_context *context, size_t size); * * name: A string identifier giving this allocation a name * size: How many bytes to allocate - * ops: a struct with pointers to callback functions (see above) + * ops: a struct with pointers to callback functions (see above). + * if "ops" is NULL: Buffer is movable. * * Returns: A positive integer handle identifying this allocation, or * a negative value on error (0 is also not a valid handle) -- cgit