node_pthread.h File Reference

#include <pthread.h>

Include dependency graph for node_pthread.h:

Go to the source code of this file.

Data Structures
struct	RBT_NODE_ROOT_T

Macros
#define	RBT_NODE_ROOT_READ(root, func, ...)
#define	RBT_NODE_ROOT_WRITE(root, func, ...)

Typedefs
typedef struct RBT_NODE_ROOT_T	RBT_NODE_ROOT_T

Functions
RBT_NODE_ROOT_T	RBT_NODE_NEW ()
	Create a new root node. More...

Detailed Description

Author

Xyne

Copyright

GPL2 only

This file is included automatically by node.h when certain macros are defined. It provides macros and functions for using rabbit trees in a threadsafe way when using pthreads.

Warning

This is currently untested.

Macro Definition Documentation

RBT_NODE_ROOT_READ

#define RBT_NODE_ROOT_READ	(		root,
			func,
			...
	)

Value:

pthread_mutex_lock(&(root.mutex)); \
while (root.writers) \
{ \
  pthread_cond_wait(&(root.cond), &(root.mutex)); \
} \
root.readers ++; \
pthread_mutex_unlock(&(root.mutex)); \
func(root.node, ##__VA_ARGS__); \
pthread_mutex_lock(&(root.mutex)); \
root.readers --; \
if (! root.readers) \
{ \
  pthread_cond_signal(&(root.cond)); \
} \
pthread_mutex_unlock(&(root.mutex))

Execute a read-only operation on the root node. This will prevent any write operation from interfering with the tree while the read operation occurs.

The steps:

1. Lock the mutex.
2. Wait for writers to finish.
3. Increment readers to prevent writes from occuring while reading.
4. Unlock the mutex to enable concurrent reads and the queuing of writes.
5. Proceed with read.
6. Lock the mutex.
7. Decrement readers.
8. Signal other threads on last reader.
9. Unlock the mutex.

Parameters

[in]	root	The root node structure.
[in]	func	The function to call. The first argument will be the node followed by any additional arguments.
[in]	...	Additional arguments to pass to the function.

RBT_NODE_ROOT_WRITE

#define RBT_NODE_ROOT_WRITE	(		root,
			func,
			...
	)

Value:

pthread_mutex_lock(&(root.mutex)); \
root.writers ++; \
while (root.readers) \
{ \
  pthread_cond_wait(&(root.cond), &(root.mutex)); \
} \
func(root.node, ##__VA_ARGS__); \
root.writers --; \
pthread_cond_signal(&(root.cond)); \
pthread_mutex_unlock(&(root.mutex))

Execute a write operation on the root node. This will prevent any other write operation from interfering with the tree while the operation occurs.

The operation will wait for all read operations to finish.

The steps:

1. Lock the mutex and increment writers to indicate that a write is pending.
2. Wait for all readers to finish.
3. Proceed with write. Other writes cannot proceed until the mutex is unlocked.
4. Decrement writers to indicate that write is complete.
5. Signal other threads.
6. Unlock mutex.

Parameters

[in]	root	The root node structure.
[in]	func	The function to call. The first argument will be the node followed by any additional arguments.
[in]	...	Additional arguments to pass to the function.

Typedef Documentation

RBT_NODE_ROOT_T

typedef struct RBT_NODE_ROOT_T RBT_NODE_ROOT_T

A convenient wrapper around root nodes to provide thread safety.

Function Documentation

RBT_NODE_NEW()

RBT_NODE_ROOT_T RBT_NODE_NEW

(

)

Create a new root node.

Create a new, empty root node. The root node type is a wrapper struct around the node type. It includes mutexes and other variables that are used to protect the data in the tree from corruption caused by concurrent writes.

See also

RBT_NODE_ROOT_READ RBT_NODE_ROOT_WRITE