TsctlThread

Certain parts of libtsctl, such as the CAN server, required threads. However, most of the library does not require threads to run. Therefore, if your program does not need threads and none of the functionality in libtsctl that you are using requires threads, it is not necessary to link against (e.g.) pthreads.

To accomodate either threads or thread-less programming, libtsctl abstracts away threads into the Thread object. If you need to use threads, you must include PThread.o in your dependencies, while if you do no, include NoThread.o; there are pre-defined build targets libtsctl-pthread.a and libtsctl.a which do the same thing, respectively. You may also need to #define THREAD_USE_POSIX however this is planned to be deprecated soon.

The Thread object encapsulates thread related tasks and implements them in PThread.c to use pthreads, and NoThread.c to use no-ops for most operations.

If your program uses threads and libtsctl, you must call the ThreadInit() function before calling any other thread related functions.

If you need to use threads in your program which call libtsctl function, you must use the Thread object.

The Thread API defines the following functions:

int ThreadInit();

Call this function to initialize the Thread sub-system before calling any other thread functions, either in the Thread object, or pthreads.

void ThreadFini(void *threadptr);

The parameter passed is a pointer to the Thread object. This function properly disposes of the internals of the Thread object passed.

Thread *ThreadNew(char *name,int inst,ThreadFunction func,int socket,
                 void *data,ThreadDestructor destor);

Create and start a new thread. The first and second parameters are for the purpose of identification; they can be whatever the user desires. The third parameter is a pointer to a function taking a void pointer and returning void; this function will be called in the new thread. The socket parameter is used if the thread is to be a server function, normally this is only meaningful if the func parameter is the "Server" function present in PThread.c. The data parameter is any additional data to be passed to the new thread. Note that the pointer to the thread function "func" is not this pointer, it is a pointer to the Thread struct, to get the data pointer dereference the data element of that structure. The final parameter is a pointer to a function to act as a destructor, performing any necessary shutdown before the thread terminates. It can be null if not required.

int ThreadEnterBlock();

This function is provided for the case of a server which may need to enter a system call which may block, but which is connected to a socket and needs to terminate that system call if the socket disconnects. This prevents sockets from lingering on long-blocking system calls such as sleeps.

int ThreadLeaveBlock();

This function is to be called after finished the blocking call following a ThreadEnterBlock call.

unsigned ThreadMutexAllocate(int);

This function allocates the specified number of mutexes, and returns the mutex number of the first one. If multiple mutexes are allocated they will have sequentially assigned numbers.

unsigned ThreadLockAllocate(int);

This function allocates the specified number of read/write locks, and returns the lock number of the first one. If multiple locks are allocated they will have sequentially assigned numbers.

unsigned ThreadMutexCount();

This function returns the total number of mutexes allocated.

unsigned ThreadLockCount();

This function returns the total number of locks allocated.

int ThreadMutexLock(unsigned num,int mode);

This function tries to lock the specified mutex number with the given mode.

The mode **LOCK_TRY** makes the call non-blocking: if the call would block a negative error code is returned. Otherwise, the call blocks until the lock is acquired. The mode **LOCK_FOD** makes the call fail if a deadlock would occur - this is currently unimplemented.

int ThreadMutexUnlock(unsigned num);

This function releases a mutex that has previously been acquired by ThreadMutexLock.

void ThreadUnlockAll(Thread *);

This function releases all mutexes and locks currently held by the thread. It is intended to be used from a destructor function or similar place where it is inconvenient to have to track what mutexes and locks are currently held.

int ThreadWait(int (*f)(int),unsigned num,int mode);

This function uses the specific lock number *num* to wait for a signal, at which time it calls the function passed by reference in the first argument. The *mode* argument is currently unused and should be 0.

int ThreadSignalIf(int (*f)(int),unsigned num);

This function calls the function passed by reference in the first parameter, passing the *num* parameter as argument. If the function returns true, then a signal is sent to the thread waiting on the specific lock number *num*. Returns true if the function was called, otherwise it returns false.

int ThreadLockW(unsigned num,int mode);

This function attempts to acquire a write (exclusive) lock for the specified lock number. Note that lock numbers exist in a different space from mutex numbers, so lock 0 and mutex 0 are not the same thing. If **TRY_LOCK** is passed as the mode, then the function will return failure immediately if the lock would block, otherwise the call blocks until the lock is acquired.

int ThreadLockR(unsigned num,int mode);

This function attempts to acquire a read (non-exclusive) lock for the specified lock number. Note that lock numbers exist in a different space from mutex numbers, so lock 0 and mutex 0 are not the same thing. If **TRY_LOCK** is passed as the mode, then the function will return failure immediately if the lock would block, otherwise the call blocks until the lock is acquired.

int ThreadUnlockW(unsigned num);

This function releases the write lock previously acquired with the ThreadLockW function.

int ThreadUnlockR(unsigned num);

This function releases the read lock previously acquired with the ThreadLockR function.

Thread *ThreadLockHolder(unsigned num);

This function returns a pointer to the thread holding the specified lock, or null if no thread currently holds it. If multiple threads hold locks, a read lock holder will be returned.

Thread *ThreadMutexHolder(unsigned num);

This function returns a pointer to the thread holding the specified mutex, or null if no thread currently holds it.