Merge branch 'release/1.3'

[reservoir_sample] / reservoir.h

diff --git a/reservoir.h b/reservoir.h
index c056ac567e733ce262f93cd16be22f0b724d97b3..e59e00af54e98b9f0c52230a56e6c6b40e72e2dc 100644 (file)
--- a/reservoir.h
+++ b/reservoir.h
@@ -9,7 +9,10 @@
 #include "notify.h"
 #endif /* NDEBUG */
 
-/* A pool of buf_t */
+/*
+       A size-limited pool of buf_t entries.  When the reservoir is filled with
+       more entries than there is room for, some spill away and are lost.
+*/
 
 typedef struct reservoir_ {
        size_t reservoir_sz; /* allocated slots */
@@ -19,6 +22,7 @@ typedef struct reservoir_ {
 } *reservoir_t;
 
 #ifndef NDEBUG
+/*     For debugging, dump an entire reservoir's contents. */
 #define D_RESERVOIR(__r__) do {\
        size_t i;\
                NOTIFY_DEBUG("reservoir:%p sz: %zu used:%zu tally:%zu", (__r__), (__r__)->reservoir_sz, (__r__)->reservoir_used, (__r__)->reservoir_tally);\
@@ -31,30 +35,36 @@ typedef struct reservoir_ {
 #endif /* NDEBUG */
 
 /*     reservoir_new
-       Allocate and return a new reservoir capable of holding #sz bufs.
+               Allocate and return a new reservoir capable of holding #sz buf_t
+       entries.
 */
 reservoir_t reservoir_new(size_t sz);
 
+/*     reservoir_del
+               Deallocate the reservoir pointed to by #preservoir.
+*/
+void reservoir_del(reservoir_t *preservoir);
+
 /*     reservoir_grow
-       Increase the storage capacity of the reservoir pointed to by #preservoir
-       by #growby bufs.
+               Increase the storage capacity of the reservoir pointed to by
+       #preservoir by #growby entries.
 */
 int reservoir_grow(reservoir_t *preservoir, size_t growby);
 
 /*     reservoir_remember
-               Remember #buf, forgetting another buf at random if the reservoir
-               pointed to by #preservoir is already full to capacity.
+               Remember #buf, forgetting (and freeing) another buf_t chosen at random
+       if the reservoir pointed to by #preservoir is already full to capacity.
 */
 void reservoir_remember(reservoir_t reservoir, buf_t buf);
 
 /*     reservoir_write
-       Write the contents of the bufs within #reservoir to #fd, each with a
-       trailing #delim.
+               Write the contents of the buf_t entries within #reservoir to #fd, each
+       with a trailing #delim character.
 */
 int reservoir_write(int fd, reservoir_t reservoir, char delim);
 
 /*     reservoir_write_meta
-       Write metadata of #reservoir and #samples to fd.
+               Write metadata about #reservoir and #samples to fd.
 */
 int reservoir_write_meta(int fd, reservoir_t reservoir, unsigned long samples, char delim);