X-Git-Url: http://git.squeep.com/?p=reservoir_sample;a=blobdiff_plain;f=reservoir.h;fp=reservoir.h;h=e59e00af54e98b9f0c52230a56e6c6b40e72e2dc;hp=c056ac567e733ce262f93cd16be22f0b724d97b3;hb=c09f96c65c1d62b2f21bf592e5927c3e07e2906b;hpb=b3b907c563ea44e7129cbb474740ea55459b1533

diff --git a/reservoir.h b/reservoir.h
index c056ac5..e59e00a 100644
--- 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);