diff options
author | Thomas Jarosch <tomj@simonv.com> | 2015-01-02 18:41:30 +0100 |
---|---|---|
committer | Thomas Jarosch <tomj@simonv.com> | 2015-01-02 18:51:15 +0100 |
commit | 66df5f3891779f8d55dd5afba1db466cea2cc2e9 (patch) | |
tree | 45d076287808f91ca434e27c1dac4066b3c48e73 | |
parent | 726537508737351d028c6730d30d9ec38fa34e4e (diff) | |
download | rockbox-66df5f3891779f8d55dd5afba1db466cea2cc2e9.tar.gz rockbox-66df5f3891779f8d55dd5afba1db466cea2cc2e9.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.c | 11 | ||||
-rw-r--r-- | firmware/core_alloc.c | 6 | ||||
-rw-r--r-- | firmware/include/buflib.h | 13 |
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) | |||
481 | buflib_buffer_shift(ctx, -size); | 481 | buflib_buffer_shift(ctx, -size); |
482 | } | 482 | } |
483 | 483 | ||
484 | /* Allocate a buffer of size bytes, returning a handle for it */ | 484 | /* Allocate a buffer of size bytes, returning a handle for it. |
485 | * Note: Buffers are movable since NULL is passed for "ops". | ||
486 | Don't pass them to functions that call yield() */ | ||
485 | int | 487 | int |
486 | buflib_alloc(struct buflib_context *ctx, size_t size) | 488 | buflib_alloc(struct buflib_context *ctx, size_t size) |
487 | { | 489 | { |
@@ -492,8 +494,11 @@ buflib_alloc(struct buflib_context *ctx, size_t size) | |||
492 | * | 494 | * |
493 | * The additional name parameter gives the allocation a human-readable name, | 495 | * The additional name parameter gives the allocation a human-readable name, |
494 | * the ops parameter points to caller-implemented callbacks for moving and | 496 | * the ops parameter points to caller-implemented callbacks for moving and |
495 | * shrinking. NULL for default callbacks (which do nothing but don't | 497 | * shrinking. |
496 | * prevent moving or shrinking) | 498 | * |
499 | * If you pass NULL for "ops", buffers are movable by default. | ||
500 | * Don't pass them to functions that call yield() like I/O. | ||
501 | * Buffers are only shrinkable when a shrink callback is given. | ||
497 | */ | 502 | */ |
498 | 503 | ||
499 | int | 504 | 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) | |||
52 | return ret; | 52 | return ret; |
53 | } | 53 | } |
54 | 54 | ||
55 | /* Allocate memory in the "core" context. See documentation | ||
56 | * of buflib_alloc_ex() for details. | ||
57 | * | ||
58 | * Note: Buffers allocated by this functions are movable. | ||
59 | * Don't pass them to functions that call yield() | ||
60 | * like disc input/output. */ | ||
55 | int core_alloc(const char* name, size_t size) | 61 | int core_alloc(const char* name, size_t size) |
56 | { | 62 | { |
57 | return buflib_alloc_ex(&core_ctx, size, name, NULL); | 63 | 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 { | |||
94 | * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_MOVE if movement | 94 | * Return: Return BUFLIB_CB_OK, or BUFLIB_CB_CANNOT_MOVE if movement |
95 | * is impossible at this moment. | 95 | * is impossible at this moment. |
96 | * | 96 | * |
97 | * If NULL: this allocation must not be moved around by the buflib when | 97 | * If NULL: this allocation must not be moved around |
98 | * compation occurs | 98 | * by the buflib when compaction occurs. Attention: Don't confuse |
99 | * that with passing NULL for the whole callback structure | ||
100 | * to buflib_alloc_ex(). This would enable moving buffers by default. | ||
101 | * You have to pass NULL inside the "struct buflib_callbacks" structure. | ||
99 | */ | 102 | */ |
100 | int (*move_callback)(int handle, void* current, void* new); | 103 | int (*move_callback)(int handle, void* current, void* new); |
101 | /** | 104 | /** |
@@ -193,6 +196,9 @@ bool buflib_context_relocate(struct buflib_context *ctx, void *buf); | |||
193 | * | 196 | * |
194 | * size: How many bytes to allocate | 197 | * size: How many bytes to allocate |
195 | * | 198 | * |
199 | * This function passes NULL for the callback structure "ops", so buffers | ||
200 | * are movable. Don't pass them to functions that yield(). | ||
201 | * | ||
196 | * Returns: A positive integer handle identifying this allocation, or | 202 | * Returns: A positive integer handle identifying this allocation, or |
197 | * a negative value on error (0 is also not a valid handle) | 203 | * a negative value on error (0 is also not a valid handle) |
198 | */ | 204 | */ |
@@ -205,7 +211,8 @@ int buflib_alloc(struct buflib_context *context, size_t size); | |||
205 | * | 211 | * |
206 | * name: A string identifier giving this allocation a name | 212 | * name: A string identifier giving this allocation a name |
207 | * size: How many bytes to allocate | 213 | * size: How many bytes to allocate |
208 | * ops: a struct with pointers to callback functions (see above) | 214 | * ops: a struct with pointers to callback functions (see above). |
215 | * if "ops" is NULL: Buffer is movable. | ||
209 | * | 216 | * |
210 | * Returns: A positive integer handle identifying this allocation, or | 217 | * Returns: A positive integer handle identifying this allocation, or |
211 | * a negative value on error (0 is also not a valid handle) | 218 | * a negative value on error (0 is also not a valid handle) |