Initial commit

Include/ZUtil/ZConcurrency.hpp

@@ -0,0 +1,137 @@
+/*
+	ZConcurrency.hpp
+	Author : James Russell, Patrick Baggett
+
+	Purpose :	Provides a number of primitives for building concurrent programs. Each supported
+	            platform has a separate implementation.
+
+	Changelog
+	1/24/11 - Creation (jcrussell)
+	3/17/11 - Major change to support events, mutexes, thread local storage, and semaphores. (ptbaggett)
+*/
+
+#pragma once
+
+#ifndef _ZCONCURRENCY_HPP
+#define _ZCONCURRENCY_HPP
+
+#include <ZUtil/ZUtilBuild.hpp>
+#include <ZUtil/ZSemaphore.hpp>
+#include <ZUtil/ZMutex.hpp>
+#include <ZUtil/ZEvent.hpp>
+#include <ZUtil/ZReadWriteLock.hpp>
+
+//Used to indicate an indefinite wait
+#define ZWAIT_INFINITE (~((uint32_t)0))
+
+//Typedef for a thread handle
+typedef void* ZThreadHandle;
+
+/*
+ZEngine thread data, used as a context for threads. The fields here should not be accessed directly.
+*/
+struct ZThreadContext
+{
+	//The handle to this thread
+	ZThreadHandle Thread;
+
+	//The id given to this thread. Unique, but may be reused after thread is destroyed
+	uint32_t ThreadId;
+
+	//The return status this thread exited with (invalid unless Thread == NULL)
+	int ThreadExitStatus;
+
+	//Default Constructor
+	ZThreadContext() { Invalidate(); }
+
+	//Returns if it's valid
+	bool IsValid() const { return Thread != NULL; }
+
+	//Marks a thread context as invalid
+	void Invalidate() { Thread = NULL; ThreadId = 0; ThreadExitStatus = 0; }
+};
+
+/*
+Namespace used for static access to low-level thread functionality.
+*/
+namespace ZConcurrency
+{
+	/*
+	ZThreadContext CreateThread()
+	
+	Creates a thread instance that will begin running the provided function.
+	The thread context should be cleaned up with DestroyThread() after the
+	thread exits (use WaitThread() to ensure it is exited).
+
+	@param _func - function that the thread will execute.  Should be of return type
+		int and take a void* as an argument.
+	@param _arg - the argument that is passed to the function.
+	
+	@return (ZThreadContext) - thread context, used as a handle to the thread
+	*/
+	ZThreadContext CreateThread(int(*_func)(void*), void *_arg);
+
+	/*
+	void DestroyThread()
+	
+	Frees memory associated with a thread context. This should only be called
+	after the thread is known to be dead (e.g. using WaitThread()). As implied
+	by the last comment, this does not kill the OS thread if it was already
+	running.
+
+	@param _context - Thread context to be cleaned up
+	@return (void)
+	*/
+	void DestroyThread(ZThreadContext& _context);
+
+	/*
+	void SleepThread()
+
+	Causes the calling thread to sleep for a minimum of the specified time (in ms).
+
+	@param _ms - the specified time to sleep (in ms)
+	@return (void)
+	*/
+	void SleepThread(uint32_t _ms);
+
+	/*
+	int GetThreadId()
+
+	Gets the thread ID of the calling thread.
+
+	@return (uint32_t) -  int that is the thread id of the calling thread
+	*/
+	uint32_t GetThreadId();
+	
+	/*
+	unsigned int GetTicks()
+
+	Gets the tick count since the last call to GetTicks.
+
+	@return (uint64_t) - the count (in ms) since program start.
+	*/
+	uint64_t GetTicks();
+	
+	/*
+	int WaitThread()
+
+	Waits for a thread to terminate.  This is the only way to ensure thread resources are
+	returned.  The termination code from the thread is stored in the thread context.
+
+	@param _context - the handle returned from CreateThread (the termination code is stored here)
+	@return (bool) - true if the thread terminated, false otherwise
+	*/
+	bool WaitThread(ZThreadContext& _context);
+
+	/*
+	void YieldThread()
+
+	Causes the calling thread to yield execution to another thread.
+
+	@return (void)
+	*/
+	void YieldThread();
+}
+
+#endif
+