drain.h File Reference

#include <keel/allocator.h>
#include <stddef.h>
#include <sys/types.h>

Include dependency graph for drain.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlDrain
	Backpressure write buffer. More...

Typedefs
typedef ssize_t(*	KlDrainWriteFn) (const char *data, size_t len, void *ctx)
	Write function for KlDrain.
typedef void(*	KlDrainCb) (void *ctx)
	Drain callback — fired when buffer transitions non-empty → empty.

Functions
void	kl_drain_init (KlDrain *d, KlDrainWriteFn write_fn, void *write_ctx, KlAllocator *alloc)
	Initialize a drain buffer.
void	kl_drain_set_max_size (KlDrain *d, size_t max_size)
	Set maximum buffer size.
void	kl_drain_on_drain (KlDrain *d, KlDrainCb cb, void *ctx)
	Register a drain callback.
int	kl_drain_write (KlDrain *d, const char *data, size_t len)
	Write data through the drain.
int	kl_drain_flush (KlDrain *d)
	Flush buffered data.
int	kl_drain_pending (const KlDrain *d)
	Check if data is pending.
size_t	kl_drain_buffered (const KlDrain *d)
	Get number of buffered bytes.
void	kl_drain_free (KlDrain *d)
	Free drain buffer.

Typedef Documentation

KlDrainWriteFn

typedef ssize_t(* KlDrainWriteFn) (const char *data, size_t len, void *ctx)

Write function for KlDrain.

Parameters

data	Data to write.
len	Data length.
ctx	Writer context.

Returns

>0 bytes written, 0 would-block, -1 error.

KlDrainCb

typedef void(* KlDrainCb) (void *ctx)

Drain callback — fired when buffer transitions non-empty → empty.

Function Documentation

kl_drain_init()

void kl_drain_init	(	KlDrain *	d,
		KlDrainWriteFn	write_fn,
		void *	write_ctx,
		KlAllocator *	alloc
	)

Initialize a drain buffer.

Buffer is lazy-allocated on first would-block.

Parameters

d	Drain handle (caller-owned).
write_fn	Underlying writer.
write_ctx	Writer context.
alloc	Allocator for buffer.

kl_drain_set_max_size()

void kl_drain_set_max_size	(	KlDrain *	d,
		size_t	max_size
	)

Set maximum buffer size.

Parameters

d	Drain handle.
max_size	Hard cap on buffered bytes (0 = unlimited).

kl_drain_on_drain()

void kl_drain_on_drain	(	KlDrain *	d,
		KlDrainCb	cb,
		void *	ctx
	)

Register a drain callback.

Fires when buffer transitions from non-empty to empty.

Parameters

d	Drain handle.
cb	Callback (NULL to clear).
ctx	Callback context.

kl_drain_write()

int kl_drain_write	(	KlDrain *	d,
		const char *	data,
		size_t	len
	)

Write data through the drain.

If buffer is non-empty, appends (preserves ordering). Otherwise writes directly; buffers only the unaccepted remainder on partial/EAGAIN.

Parameters

d	Drain handle.
data	Data to write.
len	Data length.

Returns

0 on success (all written or buffered), -1 on error.

kl_drain_flush()

int kl_drain_flush

(

KlDrain *

d

)

Flush buffered data.

Loops write_fn on buffered data. Fires on_drain when buffer empties.

Parameters

d	Drain handle.

Returns

0=drained, 1=more pending, -1=error.

kl_drain_pending()

int kl_drain_pending

(

const KlDrain *

d

)

Check if data is pending.

Parameters

d	Drain handle.

Returns

1 if data pending, 0 if empty.

kl_drain_buffered()

size_t kl_drain_buffered

(

const KlDrain *

d

)

Get number of buffered bytes.

Parameters

d	Drain handle.

Returns

Bytes pending in buffer.

kl_drain_free()

void kl_drain_free

(

KlDrain *

d

)

Free drain buffer.

Frees the internal buffer. Does not free the drain struct itself (caller-owned). Safe to call on an already-freed drain.

Parameters

d	Drain handle.