#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 */
} *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);\
#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);