I/O Thread

A system to queue up blocking I/O operations to run on a separate thread. More...


Files
file	iothread.c
	Implementation for a thread used for blocking I/O operations.
file	iothread.h
	Interface to a thread for blocking I/O operations.
Data Structures
struct	Operation_t
	Stores information on a queued operation. More...
Defines
#define	FLAG_CANCEL 1
	Bit flag used with opFlags to indicate that the current operation should return early.
#define	FLAG_TERM 2
	Bit flag used with opFlags to indicate that the I/O thread should terminate.
#define	IO_QUEUE_SIZE 4
	The size of the queue for I/O operations.
Typedefs
typedef void(*)	ioOperation (void *data)
	The function prototype of all functions called by the I/O thread to perform blocking operations.
Functions
Bool	CancelOperations ()
	Attempts to cancel all operations currently queued on the I/O thread.
static int	ioThread (void *ignore)
	The thread body that waits for queued I/O requests and runs them.
Bool	IsCancelationRequested ()
	Tells if a request has been made to cancel the current operation on the I/O thread through a call to CancelOperations().
int	QueueOperation (ioOperation op, void *data)
	Adds an operation to the queue of pending blocking operations.
void	StartIOThread ()
	Starts the I/O thread.
void	StopIOThread ()
	Terminates the I/O thread.
Variables
static SDL_cond *	notify
	Used to notify the I/O thread that there is work to do.
static int	opFlags = 0
	The flags used to indicate when: the running operation should return early the I/O thread should terminate.
static struct Operation_t	queue [4]
	The operation queue.
static int	queueLen = 0
	The number of operations in the queue.
static SDL_mutex *	queueMutex = NULL
	The semaphore used to control access to the operation queue.
static int	queueNext = 0
	The index of the next operation in the queue.
static SDL_Thread *	thread = NULL
	A reference to information about the running I/O thread.

Detailed Description

A system to queue up blocking I/O operations to run on a separate thread.

First, StartIOThread() must be called. Then asynchronous operations may be queued by calling QueueOperation(). When finished, call StopIOThread() to terminate the thread and cleanup gracefully. To cancel all queued operations and the running operation, call CancelOperations(). Long running operations should call IsCancelationRequested() to see if they should return early.

The random number generator is gaurenteed to be ready for use by operations running on the I/O thread.

Author:: Jeff Jackowski

Define Documentation

#define FLAG_CANCEL 1

Bit flag used with opFlags to indicate that the current operation should return early.

For internal use only.

Definition at line 104 of file iothread.c.

Referenced by CancelOperations(), IsCancelationRequested(), and StopIOThread().

#define FLAG_TERM 2

Bit flag used with opFlags to indicate that the I/O thread should terminate.

For internal use only.

Definition at line 112 of file iothread.c.

Referenced by ioThread(), and StopIOThread().

#define IO_QUEUE_SIZE 4

The size of the queue for I/O operations.

For best performance, use a power of two.

Definition at line 50 of file iothread.h.

Referenced by ioThread(), and QueueOperation().

Typedef Documentation

typedef void(*) ioOperation(void *data)

The function prototype of all functions called by the I/O thread to perform blocking operations.

Parameters:

data

A pointer to arbitrary data used by the operation.

Definition at line 77 of file iothread.h.

Function Documentation

Bool CancelOperations ( )

Attempts to cancel all operations currently queued on the I/O thread.

Sets the cancel request flag in hopes the currently running operation will terminate early, and removes all operations waiting in the queue.

Returns:: True on success, false on failure.

Author:: Jeff Jackowski

Definition at line 262 of file iothread.c.

References FALSE, FLAG_CANCEL, opFlags, queueLen, queueMutex, thread, and TRUE.

Referenced by NetDisconnect().

static int ioThread ( void * ignore ) [static]

The thread body that waits for queued I/O requests and runs them.

For internal use only.

Author:: Jeff Jackowski

Definition at line 120 of file iothread.c.

References Operation_t::data, FLAG_TERM, IO_QUEUE_SIZE, notify, Operation_t::op, opFlags, queue, queueLen, queueMutex, and RandInit().

Referenced by StartIOThread().

Here is the call graph for this function:

Bool IsCancelationRequested ( )

Tells if a request has been made to cancel the current operation on the I/O thread through a call to CancelOperations().

Long running operations should call this function periodically so they can terminate early on request.

Returns:: True if the operation should quit now.

Author:: Jeff Jackowski

Definition at line 258 of file iothread.c.

References FLAG_CANCEL, and opFlags.

Referenced by ClientSync(), DiscoverConnectServer(), and GetSamples().

int QueueOperation	(	ioOperation	op,
		void *	data
	)

Adds an operation to the queue of pending blocking operations.

Parameters:

	op	The function that will perform the operation.
	data	Arbitrary datat that will be passed to the operation function.

Returns:: The number of operations that are queued. If the queue is already full, -1 is returned and the operation is not queued. If there is an error while locking the queue semaphore, -2 is returned.

Author:: Jeff Jackowski

Definition at line 231 of file iothread.c.

References Operation_t::data, IO_QUEUE_SIZE, notify, Operation_t::op, queue, queueLen, queueMutex, and queueNext.

Referenced by NetDisconnect(), NetInit(), NetInitSrv(), StartAddrLookup(), StartClientTimeSync(), StartNameLookup(), and StartStrNameLookup().

void StartIOThread ( )

Starts the I/O thread.

This must be called prior to queuing any operations. The thread will initialize the random number generator to handle the case where the generator uses therad local data.

Bug:: On Linux with SDL 1.2.8, valgrind shows that when SDL_SYS_CreateThread() makes a call to pthread_create(), two things are allocated totaling about 10.5KB that are not deallocated.