summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Jarosch <tomj@simonv.com>2015-01-02 18:41:30 +0100
committerThomas Jarosch <tomj@simonv.com>2015-01-02 18:51:15 +0100
commit66df5f3891779f8d55dd5afba1db466cea2cc2e9 (patch)
tree45d076287808f91ca434e27c1dac4066b3c48e73
parent726537508737351d028c6730d30d9ec38fa34e4e (diff)
downloadrockbox-66df5f3.tar.gz
rockbox-66df5f3.tar.bz2
rockbox-66df5f3.zip
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
-rw-r--r--firmware/buflib.c11
-rw-r--r--firmware/core_alloc.c6
-rw-r--r--firmware/include/buflib.h13
3 files changed, 24 insertions, 6 deletions
diff --git a/firmware/buflib.c b/firmware/buflib.c
index a47f0a0e62..0e00f1fe1f 100644
--- a/firmware/buflib.c
+++ b/firmware/buflib.c
@@ -481,7 +481,9 @@ buflib_buffer_in(struct buflib_context *ctx, int size)
buflib_buffer_shift(ctx, -size);
}
-/* Allocate a buffer of size bytes, returning a handle for it */
+/* Allocate a buffer of size bytes, returning a handle for it.
+ * Note: Buffers are movable since NULL is passed for "ops".
+ Don't pass them to functions that call yield() */
int
buflib_alloc(struct buflib_context *ctx, size_t size)
{
@@ -492,8 +494,11 @@ buflib_alloc(struct buflib_context *ctx, size_t size)
*
* The additional name parameter gives the allocation a human-readable name,
* the ops parameter points to caller-implemented callbacks for moving and
- * shrinking. NULL for default callbacks (which do nothing but don't
- * prevent moving or shrinking)
+ * shrinking.
+ *
+ * If you pass NULL for "ops", buffers are movable by default.
+ * Don't pass them to functions that call yield() like I/O.
+ * Buffers are only shrinkable when a shrink callback is given.
*/
int
diff --git a/firmware/core_alloc.c b/firmware/core_alloc.c
index 58e12141e1..53e5bf4a97 100644
--- a/firmware/core_alloc.c
+++ b/firmware/core_alloc.c
@@ -52,6 +52,12 @@ bool core_test_free(void)
return ret;
}
+/* Allocate memory in the "core" context. See documentation
+ * of buflib_alloc_ex() for details.
+ *
+ * Note: Buffers allocated by this functions are movable.
+ * Don't pass them to functions that call yield()
+ * like disc input/output. */
int core_alloc(const char* name, size_t size)
{
return buflib_alloc_ex(&core_ctx, size, name, NULL);
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)