Buflib: Clarification about invalid handles

* Enhance allocation function comments to better state the return value and what an invalid value is
* Change clients to check for "< 0" instead of "<= 0" or "== 0"
* Return -1 or -2 depending on the exact failure in buflib_alloc_ex.

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@30469 a1c6a512-1295-4272-9138-f99709370657

5 files changed, 15 insertions, 10 deletions

diff --git a/apps/filetypes.c b/apps/filetypes.c
index 942ff329fe..8f2e91222a 100644
--- a/apps/filetypes.c
+++ b/apps/filetypes.c
@@ -344,7 +344,7 @@ void  filetype_init(void)
 
     strdup_bufsize = filesize(fd);
     strdup_handle = core_alloc_ex("filetypes", strdup_bufsize, &ops);
-    if (strdup_handle <= 0)
+    if (strdup_handle < 0)
         return;
     read_builtin_types();
     read_config(fd);
diff --git a/apps/plugins/pictureflow/pictureflow.c b/apps/plugins/pictureflow/pictureflow.c
index c13aca1a95..a572586886 100644
--- a/apps/plugins/pictureflow/pictureflow.c
+++ b/apps/plugins/pictureflow/pictureflow.c
@@ -1520,9 +1520,11 @@ int read_pfraw(char* filename, int prio)
                 sizeof( pix_t ) * bmph.width * bmph.height;
 
     int hid;
-    while (!(hid = rb->buflib_alloc(&buf_ctx, size)) && free_slide_prio(prio));
+    do {
+        hid = rb->buflib_alloc(&buf_ctx, size);
+    } while (hid < 0 && free_slide_prio(prio));
 
-    if (!hid) {
+    if (hid < 0) {
         rb->close( fh );
         return 0;
     }
diff --git a/apps/scrobbler.c b/apps/scrobbler.c
index 78414f3d88..06c957cd6c 100644
--- a/apps/scrobbler.c
+++ b/apps/scrobbler.c
@@ -255,7 +255,7 @@ int scrobbler_init(void)
         return -1;
 
     scrobbler_cache = core_alloc("scrobbler", SCROBBLER_MAX_CACHE*SCROBBLER_CACHE_LEN);
-    if (scrobbler_cache <= 0)
+    if (scrobbler_cache < 0)
     {
         logf("SCROOBLER: OOM");
         return -1;
diff --git a/firmware/buflib.c b/firmware/buflib.c
index f7ef35ea8b..7c5f3d208e 100644
--- a/firmware/buflib.c
+++ b/firmware/buflib.c
@@ -425,7 +425,7 @@ handle_alloc:
                     goto handle_alloc;
                 }
             }
-            return 0;
+            return -1;
         }
     }
 
@@ -471,7 +471,7 @@ buffer_alloc:
         } else {
             handle->val=1;
             handle_free(ctx, handle);
-            return 0;
+            return -2;
         }
     }
 
diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h
index db7b5ec50a..3d8f43ef5f 100644
--- a/firmware/include/buflib.h
+++ b/firmware/include/buflib.h
@@ -153,7 +153,8 @@ size_t buflib_available(struct buflib_context *ctx);
  *
  * size: How many bytes to allocate
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc(struct buflib_context *context, size_t size);
 
@@ -166,7 +167,8 @@ int buflib_alloc(struct buflib_context *context, size_t size);
  * size: How many bytes to allocate
  * ops: a struct with pointers to callback functions (see above)
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc_ex(struct buflib_context *ctx, size_t size, const char *name,
                     struct buflib_callbacks *ops);
@@ -188,7 +190,8 @@ int buflib_alloc_ex(struct buflib_context *ctx, size_t size, const char *name,
  * size: The actual size will be returned into size
  * ops: a struct with pointers to callback functions
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc_maximum(struct buflib_context* ctx, const char* name,
                     size_t *size, struct buflib_callbacks *ops);
@@ -233,7 +236,7 @@ bool buflib_shrink(struct buflib_context *ctx, int handle, void* newstart, size_
 /**
  * Frees memory associated with the given handle
  *
- * Returns: 0 (to invalidate handles in one line)
+ * Returns: 0 (to invalidate handles in one line, 0 is not a valid handle)
  */
 int buflib_free(struct buflib_context *context, int handle);