PureBasic - ThreadSync

Overview

PureBasic allows you to create threads so your application has the appearance of being able to run multiple pieces of code in parallel (and does do to some extent on multi-processor systems). However, there are no commands to control threads in a clean way - basically nothing to allow you to communicate and synchronise threads.

This library provides access to these features, which should always be availble as part of the Operating System (and I will not hide the fact this this library is mostly a wrapper for the underlying OS functions). The OS is our friend here because it is that which ensures that the internals of our inter-thread objects are not corrupted by multiple accesses. Note that these are aimed at threads (pieces of software which run within your application), not processes (completely separate pieces of software which run independantly).

Threads need to be used carefully because it is possible that you can have multiple access to shared resources (memory, variables, files, etc) and you need to manually ensure that you do run into trouble because of this. For example, it is not safe to modify or write to strings from more than one thread because strings share the same internal memory buffer. This is one example of where this library can help you.

Of course, any problem which needs threads to be synchronised or be able to to communicate between each other could be solved using this library. It is not only a method to prevent uncontrolled access to shared resources.

As previously mentioned, all of the abilities of this library are provided through inter-thread synchronisation and communication objects that the OS allows us to use. For the most part, when you are trying to get access to one of these objects you must wait for them. All wait commands allow you to specify a timeout, so you can either check for immediate access, wait a short time during which you may get access, or wait indefinately until you get access.

WARNING!
Under the Windows OS the DDE technology sends messages to Windows, and appears to block access while a single DDE message is fired across all windows in all applications. This means that if you have a thread with a window then it must be able to process its Window messages or your system will freeze. That means either using a command which checks for Window messages at the same time as these thread communication objects, or having timeout values which are not equal to #INFINITE. Commands which have built in #INFINITE waits will be marked in the command description. Or make sure your application cannot deadlock itself so that #INFINITE waits are acceptable.

Before we begin, it might be useful to cover some terminology. Threads can be in one of (roughly) three states when they exist. They can either be:
Running: The thread is assigned to a CPU and is currently being executed
Waiting: The thread is ready to run (for example, it is not waiting for anything) but is not assigned to a CPU and so is not running.
Suspended: The thread is waiting for something (an event, a signal, etc) and so cannot run.

Please also note that books are written about this stuff, so there are far more things to consider than what is presented here (I have not covered anything related to scheduling, priorities and so forth). This document should give you enough information to use the library in most "normal" use cases.

Library version: 1.4
Status: incomplete beta, not fully tested
Library format: C coded, LIB format, not fully split. Has debugger code.

History:
1st June 2003 Fixed big bug in method of access to shared semaphores, could have led to deadlocks.
Fixed some incorrect initialisations of complex semaphores
Changed TSSemahoreCount() so that it would not cause a thread to be suspended
31st May 2003 Semaphore commands complete, first public release.

Command Index

TSCreateSemaphore
TSDestroySemaphore
TSGetExclusiveSemaphore
TSGetSemaphore
TSLibraryOK
TSLibraryVersion
TSPutExclusiveSemaphore
TSPutSemaphore
TSSemaphoreCount

Example

..\..\Examples\BasicLibrary.pb
..\..\Examples\Semaphores.pb
..\..\Examples\SimpleSemaphores.pb
..\..\Examples\ComplexSemaphore.pb

Supported OS

Windows