h2_bucket_beam.h File Reference

#include "h2_conn_ctx.h"

Include dependency graph for h2_bucket_beam.h:

Go to the source code of this file.

Data Structures
struct	h2_blist
struct	h2_bucket_beam

Typedefs
typedef struct h2_bucket_beam	h2_bucket_beam
typedef void	h2_beam_io_callback(void *ctx, h2_bucket_beam *beam, apr_off_t bytes)
typedef void	h2_beam_ev_callback(void *ctx, h2_bucket_beam *beam)

Functions
apr_status_t	h2_beam_create (h2_bucket_beam **pbeam, conn_rec *from, apr_pool_t *pool, int id, const char *tag, apr_size_t buffer_size, apr_interval_time_t timeout)
apr_status_t	h2_beam_destroy (h2_bucket_beam *beam, conn_rec *c)
void	h2_beam_set_copy_files (h2_bucket_beam *beam, int enabled)
apr_status_t	h2_beam_send (h2_bucket_beam *beam, conn_rec *from, apr_bucket_brigade *bb, apr_read_type_e block, apr_off_t *pwritten)
apr_status_t	h2_beam_receive (h2_bucket_beam *beam, conn_rec *to, apr_bucket_brigade *bb, apr_read_type_e block, apr_off_t readbytes)
int	h2_beam_empty (h2_bucket_beam *beam)
void	h2_beam_abort (h2_bucket_beam *beam, conn_rec *c)
void	h2_beam_close (h2_bucket_beam *beam, conn_rec *c)
void	h2_beam_timeout_set (h2_bucket_beam *beam, apr_interval_time_t timeout)
apr_interval_time_t	h2_beam_timeout_get (h2_bucket_beam *beam)
void	h2_beam_buffer_size_set (h2_bucket_beam *beam, apr_size_t buffer_size)
apr_size_t	h2_beam_buffer_size_get (h2_bucket_beam *beam)
void	h2_beam_on_consumed (h2_bucket_beam *beam, h2_beam_io_callback *io_cb, void *ctx)
void	h2_beam_on_received (h2_bucket_beam *beam, h2_beam_ev_callback *recv_cb, void *ctx)
void	h2_beam_on_eagain (h2_bucket_beam *beam, h2_beam_ev_callback *eagain_cb, void *ctx)
void	h2_beam_on_send (h2_bucket_beam *beam, h2_beam_ev_callback *on_send_cb, void *ctx)
void	h2_beam_on_was_empty (h2_bucket_beam *beam, h2_beam_ev_callback *was_empty_cb, void *ctx)
int	h2_beam_report_consumption (h2_bucket_beam *beam)
apr_off_t	h2_beam_get_buffered (h2_bucket_beam *beam)
apr_off_t	h2_beam_get_mem_used (h2_bucket_beam *beam)
int	h2_beam_is_complete (h2_bucket_beam *beam)

Typedef Documentation

h2_beam_ev_callback

typedef void h2_beam_ev_callback(void *ctx, h2_bucket_beam *beam)

h2_beam_io_callback

typedef void h2_beam_io_callback(void *ctx, h2_bucket_beam *beam, apr_off_t bytes)

h2_bucket_beam

typedef struct h2_bucket_beam h2_bucket_beam

A h2_bucket_beam solves the task of transferring buckets, esp. their data, across threads with as little copying as possible.

Function Documentation

h2_beam_abort()

void h2_beam_abort	(	h2_bucket_beam *	beam,
		conn_rec *	c
	)

Abort the beam, either from receiving or sending side.

Parameters

beam	the beam to abort
c	the connection the caller is working with

h2_beam_buffer_size_get()

apr_size_t h2_beam_buffer_size_get

(

h2_bucket_beam *

beam

)

h2_beam_buffer_size_set()

void h2_beam_buffer_size_set	(	h2_bucket_beam *	beam,
		apr_size_t	buffer_size
	)

Set/get the maximum buffer size for beam data (memory footprint).

h2_beam_close()

void h2_beam_close	(	h2_bucket_beam *	beam,
		conn_rec *	c
	)

Close the beam. Make certain an EOS is sent.

Parameters

beam	the beam to abort
c	the connection the caller is working with

h2_beam_create()

apr_status_t h2_beam_create	(	h2_bucket_beam **	pbeam,
		conn_rec *	from,
		apr_pool_t *	pool,
		int	id,
		const char *	tag,
		apr_size_t	buffer_size,
		apr_interval_time_t	timeout
	)

Creates a new bucket beam for transfer of buckets across threads.

The pool the beam is created with will be protected by the given mutex and will be used in multiple threads. It needs a pool allocator that is only used inside that same mutex.

Parameters

pbeam	will hold the created beam on return
c_from	connection from which buchets are sent
pool	pool owning the beam, beam will cleanup when pool released
id	identifier of the beam
tag	tag identifying beam for logging
buffer_size	maximum memory footprint of buckets buffered in beam, or 0 for no limitation
timeout	timeout for blocking operations

h2_beam_destroy()

apr_status_t h2_beam_destroy	(	h2_bucket_beam *	beam,
		conn_rec *	c
	)

Destroys the beam immediately without cleanup.

h2_beam_empty()

int h2_beam_empty

(

h2_bucket_beam *

beam

)

Determine if beam is empty.

h2_beam_get_buffered()

apr_off_t h2_beam_get_buffered

(

h2_bucket_beam *

beam

)

Get the amount of bytes currently buffered in the beam (unread).

h2_beam_get_mem_used()

apr_off_t h2_beam_get_mem_used

(

h2_bucket_beam *

beam

)

Get the memory used by the buffered buckets, approximately.

h2_beam_is_complete()

int h2_beam_is_complete

(

h2_bucket_beam *

beam

)

Returns

!= 0 iff beam has been closed or has an EOS bucket buffered waiting to be received.

h2_beam_on_consumed()

void h2_beam_on_consumed	(	h2_bucket_beam *	beam,
		h2_beam_io_callback *	io_cb,
		void *	ctx
	)

Register a callback to be invoked on the sender side with the amount of bytes that have been consumed by the receiver, since the last callback invocation or reset.

Parameters

beam	the beam to set the callback on
io_cb	the callback or NULL, called on sender with bytes consumed
ctx	the context to use in callback invocation

Call from the sender side, io callbacks invoked on sender side, ev callback from any side.

h2_beam_on_eagain()

void h2_beam_on_eagain	(	h2_bucket_beam *	beam,
		h2_beam_ev_callback *	eagain_cb,
		void *	ctx
	)

Register a callback to be invoked on the receiver side whenever APR_EAGAIN is being returned in h2_beam_receive().

Parameters

beam	the beam to set the callback on
egain_cb	the callback or NULL, called before APR_EAGAIN is returned
ctx	the context to use in callback invocation

h2_beam_on_received()

void h2_beam_on_received	(	h2_bucket_beam *	beam,
		h2_beam_ev_callback *	recv_cb,
		void *	ctx
	)

Register a callback to be invoked on the receiver side whenever buckets have been transfered in a h2_beam_receive() call.

Parameters

beam	the beam to set the callback on
recv_cb	the callback or NULL, called when buckets are received
ctx	the context to use in callback invocation

h2_beam_on_send()

void h2_beam_on_send	(	h2_bucket_beam *	beam,
		h2_beam_ev_callback *	on_send_cb,
		void *	ctx
	)

Register a call back from the sender side to be invoked when send has added buckets to the beam. Unregister by passing a NULL on_send_cb.

Parameters

beam	the beam to set the callback on
on_send_cb	the callback to invoke after buckets were added
ctx	the context to use in callback invocation

h2_beam_on_was_empty()

void h2_beam_on_was_empty	(	h2_bucket_beam *	beam,
		h2_beam_ev_callback *	was_empty_cb,
		void *	ctx
	)

Register a call back from the sender side to be invoked when send has added to a previously empty beam. Unregister by passing a NULL was_empty_cb.

Parameters

beam	the beam to set the callback on
was_empty_cb	the callback to invoke on blocked send
ctx	the context to use in callback invocation

h2_beam_receive()

apr_status_t h2_beam_receive	(	h2_bucket_beam *	beam,
		conn_rec *	to,
		apr_bucket_brigade *	bb,
		apr_read_type_e	block,
		apr_off_t	readbytes
	)

Receive buckets from the beam into the given brigade. The caller is operating on connection to.

Parameters

beam	the beam to receive buckets from
to	the connection the receiver is working with
bb	the bucket brigade to append to
block	if the read should block when buckets are unavailable
readbytes	the amount of data the receiver wants

Returns

APR_SUCCESS when buckets were appended APR_EAGAIN on non-blocking read when no buckets are available APR_TIMEUP on blocking reads that time out APR_ECONNABORTED when beam has been aborted

h2_beam_report_consumption()

int h2_beam_report_consumption

(

h2_bucket_beam *

beam

)

Call any registered consumed handler, if any changes have happened since the last invocation.

Returns

!=0 iff a handler has been called

Needs to be invoked from the sending side.

h2_beam_send()

apr_status_t h2_beam_send	(	h2_bucket_beam *	beam,
		conn_rec *	from,
		apr_bucket_brigade *	bb,
		apr_read_type_e	block,
		apr_off_t *	pwritten
	)

Send buckets from the given brigade through the beam. This can block of the amount of bucket data is above the buffer limit.

Parameters

beam	the beam to add buckets to
from	the connection the sender operates on, must be the same as used to create the beam
bb	the brigade to take buckets from
block	if the sending should block when the buffer is full
pwritten	on return, contains the number of data bytes sent

Returns

APR_SUCCESS when buckets were added to the beam. This can be a partial transfer and other buckets may still remain in bb APR_EAGAIN on non-blocking send when the buffer is full APR_TIMEUP on blocking semd that time out APR_ECONNABORTED when beam has been aborted

h2_beam_set_copy_files()

void h2_beam_set_copy_files	(	h2_bucket_beam *	beam,
		int	enabled
	)

Switch copying of file buckets on/off.

h2_beam_timeout_get()

apr_interval_time_t h2_beam_timeout_get

(

h2_bucket_beam *

beam

)

h2_beam_timeout_set()

void h2_beam_timeout_set	(	h2_bucket_beam *	beam,
		apr_interval_time_t	timeout
	)

Set/get the timeout for blocking sebd/receive operations.