pool.h File Reference

Provides a thread-local / globally shared pool of objects. More...

#include "qev.h"

Go to the source code of this file.

Typedefs
typedef struct qev_pool	qev_pool_t
	You're not allowed to touch anything in the pool.
typedef void *(*	qev_pool_new_fn )()
	Function that creates a new instance of the managed object.

Functions
qev_pool_t *	qev_pool_new (const qev_pool_new_fn new_fn, const qev_free_fn reset_fn, const qev_free_fn free_fn, const guint local_size, const guint global_size, const gboolean preallocate)
	Creates a pool of objects. More...
void	qev_pool_free (qev_pool_t *pool)
	Closes down and cleans out all objects left in the pool.
void	qev_pool_register_thread ()
	Pools need to know about all threads that will access them before they are created. More...
void *	qev_pool_get (qev_pool_t *pool)
	Gets an object from the pool. More...
void	qev_pool_put (qev_pool_t *pool, void *obj)
	Puts an object back into the pool. More...

Detailed Description

Provides a thread-local / globally shared pool of objects.

Compared to a qev_queue, the pool performs best in situations of high contention (up to 2x as fast); when contention is low, the pool performs ~20% worse.

Author

Andrew Stone andre.nosp@m.w@cl.nosp@m.ovar..nosp@m.com

Copyright

2012-2014 Clear Channel Inc.

Function Documentation

void* qev_pool_get

(

qev_pool_t *

pool

)

Gets an object from the pool.

If no objects are available, one will be created.

Parameters

pool	The pool to retrieve the object from.

Returns

The object.

qev_pool_t* qev_pool_new	(	const qev_pool_new_fn	new_fn,
		const qev_free_fn	reset_fn,
		const qev_free_fn	free_fn,
		const guint	local_size,
		const guint	global_size,
		const gboolean	preallocate
	)

Creates a pool of objects.

Parameters

new_fn	Function that creates a new instance of the managed object
reset_fn	Resets the given object (optional)
free_fn	Frees the given object
local_size	The size of the thread-local queues. Should be a power of 2; it'll be forced to the nearest power of 2 if it isn't. You should also try to keep this kinda small.
global_size	The size of the global queue. Should be a power of 2; it'll be forced to the nearest power of 2 if it isn't.
preallocate	If the pool should be completely filled up on create.

void qev_pool_put	(	qev_pool_t *	pool,
		void *	obj
	)

Puts an object back into the pool.

Parameters

pool	The pool to put the object into.
obj	The object to add back to the pool.

void qev_pool_register_thread

(

)

Pools need to know about all threads that will access them before they are created.

This function just informs the pools of what threads will be coming in. Any thread not registered here will fall back to the global pool, and that can get slow.