The API of spThread-0.1.0
softpixel, 2002.01.11
-------------------------

In spThread, there are two structures: threads and mutexes.
Threads store information about the threads that have been created, while
Mutexes store information about arbitrary logical-locks.

The structures are provided as information to the user, but one rarely has
to use the structural data because most information can be retrieved
procedurally by passing either the thread id, or a string (i.e., "name").
The string method is provided for convenience (especially regarding debugging),
but is naturally a bit slower.

struct
{
	char	*name;		// thread name
	int	ID;		// thread ID
	int	parentID;	// creating thread ID
	void	*d;		// system-specific pointer, do not touch :^)
} spThread;

struct
{
	char	*name;		// mutex name
	char	locked;		// 0==unlocked, else locked
	int	owner;		// Owner ID
	void	*d;		// system-specific pointer, do not touch :^)
} spMutex;


There is some redundancy in the structures versus their platform specific
counterparts.  This allows for some more flexibility when it comes to
features that are not consistently supported across operating platforms.


spThread	*spThreadInit(char *name, void* (*threadfunc)(void*),void *arg);
spThreadInit creates a new thread that runs parallel to the creating
thread (could be another thread, or from the main program).  name
specifies the thread's name, threadfunc points to the function the thread
will be executing, and arg is the argument passed to threadfunc.
Returns a pointer to a new spThread struct on success; null on failure.


void		spThreadReturn(int returnCode);
spThreadReturn is the way to return in the threadfunc.  due to some
bookkeeping that also lies in this function, it is a very wise thing to
call to keep memory leaks away.  returnCode is the thread's return value,
which is not supported at this time.  This function does not return.


int		spThreadID(void);
Each thread has it's own ID.  spThreadID returns the ID of the thread that
called it.  This is used internally in many bookkeeping functions, but
has other applications as well.  This function can be called from anywhere,
even in the main program.


int		spThreadKillByID(int id);
spThreadKillByID terminates a thread with an ID of id.  returns 0 on
success, nonzero on failure.  


int		spThreadKillByName(char *name);
spThreadKillByName is the same as spThreadKillByID, but uses a name
instead.  In the case of two or more strings with the same name, the first
one created is killed.  It's probably not a good idea to depend on this,
though.  We recommend that you keep names unique.


int		spThreadWaitByID(int id);
int		spThreadWaitByName(char *name);
spThreadWaitBy* suspends the calling thread until the thread with ID id
or name name terminates.  returns 0 on success, else error.  On the windows 
platform, waiting for threads has not been tested yet.

---

spMutex		*spThreadMutexCreate(char *name);
spThreadMutexCreate creates and returns a mutex named name.  Mutexes are
normally global so all threads can use them, but they still need to be
initialized at some point.


void		spThreadMutexDestroy(spMutex *mutex);
spThreadMutexDestroy frees memory used by a mutex.  Once a mutex is freed,
it can no longer be used unless it is recreated.  calling destroy on a mutex
that is locked has no effect.


int		spThreadMutexLock(spMutex *mutex);
spThreadMutexLock blocks the calling thread until the mutex specified is
locked by that thread.  returns 0 on success, nonzero on error.  Warning:  If a
Thread has already locked a mutex, and tries to lock it again, it may
block forever.  You probably don't want this :^)


int		spThreadMutexLockByName(char *name);
This is the same as spThreadMutexLock, but it uses a mutex name rather
than the struct directly.  This keeps them from having to be global, at a
speed cost.  returns 0 on success, nonzero on error.


int		spThreadMutexTryLock(spMutex *mutex);
spThreadTryLock attempts to lock the mutex.  If the mutex is already
locked, this function returns 1.  If it does manage to get the mutex
locked, it returns 0.  any other return code indicates an error.


int		spThreadMutexTryLockByName(char *name);
This is the same as spThreadTryLock, but uses a name instead of a
structure.  returns 0 on success, else error.


int		spThreadMutexUnlock(spMutex *mutex);
spThreadMutexUnlock is called to unlock the mutex, allowing other threads
to use it.  returns 0 on success, else error.  calling Unlock on a mutex
that wasn't locked by the same thread returns an error.


int		spThreadMutexUnlockByName(char *name);
same as spThreadMutexUnlock, but uses the name rather than the
structure.

---

void		spThreadSetDebugLevel(unsigned char level);
spThreadSetDebugLevel sets the debug level within the library.  The higher
the level, the more messages one gets.  This is helpful when debugging
programs where normal debugging methods fail because it's hard to see
what's going wrong where.  256 is the maximum level, but 4 is the highest
currently used by this library.


unsigned char	spThreadGetDebugLevel(void);
this returns the current debug level.  it is 0 (off) by default.


void		spThreadSetDebugFD(FILE *fd);
spThreadSetDebugFD allows the application to route debug messages wherever
they want.  It defaults to stderr if no other ones are specified.