Synchronization objects

The syncobjs unit implements some classes which can be used when synchronizing threads in routines or classes that are used in multiple threads at once. The class is a wrapper around low-level critical section routines (semaphores or mutexes). The class can be used to send messages between threads (also known as conditional variables in Posix threads).

Exception support Dummy type PSecurityAttributes is a dummy type used in non-windows implementations, so the calls remain Delphi compatible. Handle type TEventHandle is an opaque type and should not be used in user code. Infinite waiting time Constant denoting an infinite timeout. Unix wait result TWaitResult is used to report the result of a wait operation. Event was signaled (triggered) Time-out period expired Wait operation was abandoned. An error occurred during the wait operation. Abstract synchronization object TSynchroObject is an abstract synchronization resource object. It implements 2 virtual methods Acquire which can be used to acquire the resource, and Release to release the resource. Acquire Release Acquire synchronization resource Acquire does nothing in TSynchroObject. Descendent classes must override this method to acquire the resource they manage. Release Release previously acquired synchronization resource Release does nothing in TSynchroObject. Descendent classes must override this method to release the resource they acquired through the Acquire call. Acquire Critical section

TCriticalSection is a class wrapper around the low-level TRTLCriticalSection routines. It simply calls the RTL routines in the system unit for critical section support.

A critical section is a resource which can be owned by only 1 caller: it can be used to make sure that in a multithreaded application only 1 thread enters pieces of code protected by the critical section.

Typical usage is to protect a piece of code with the following code (MySection is a TCriticalSection instance):


  // Previous code
  MySection.Acquire;
  Try
    // Protected code
  Finally
    MySection.Release;
  end;
  // Other code.

The protected code can be executed by only 1 thread at a time. This is useful for instance for list operations in multithreaded environments.

Acquire Release Enter the critical section Acquire attempts to enter the critical section. It will suspend the calling thread if the critical section is in use by another thread, and will resume as soon as the other thread has released the critical section. Release Leave the critical section Release leaves the critical section. It will free the critical section so another thread waiting to enter the critical section will be awakened, and will enter the critical section. This call always returns immediatly. Acquire Alias for Acquire Enter just calls Acquire. Leave Acquire. Alias for Release Leave just calls Release Release Enter Create a new critical section. Create initializes a new critical section, and initializes the system objects for the critical section. It should be created only once for all threads, all threads should use the same critical section instance. Destroy Destroy the criticalsection instance

Destroy releases the system critical section resources, and removes the TCriticalSection instance from memory.

Any threads trying to enter the critical section when it is destroyed, will start running with an error (an exception should be raised). Create Acquire Class encapsulating an operating system handle THandleObject is a parent class for synchronization classes that need to store an operating system handle. It introduces a property Handle which can be used to store the operating system handle. The handle is in no way manipulated by THandleObject, only storage is provided. Handle Free the instance Destroy does nothing in the Free Pascal implementation of THandleObject. Handle for this object Handle provides read-only access to the operating system handle of this instance. The public access is read-only, descendent classes should set the handle by accessing it's protected field FHandle directly. Last operating system error LastError provides read-only access to the last operating system error code for operations on Handle. Handle Event propagation object TEventObject encapsulates the BasicEvent implementation of the system unit in a class. The event can be used to notify other threads of a change in conditions. (in POSIX terms, this is a conditional variable). A thread that wishes to notify other threads creates an instance of TEventObject with a certain name, and posts events to it. Other threads that wish to be notified of these events should create their own instances of TEventObject with the same name, and wait for events to arrive. Create a new event object

Create creates a new event object with unique name AName. The object will be created security attributes EventAttributes (windows only).

The AManualReset indicates whether the event must be reset manually (if it is False, the event is reset immediatly after the first thread waiting for it is notified). InitialState determines whether the event is initially set or not.

ManualReset ResetEvent Security attributes (only used on Windows) Manual reset allowed Initial event state Name uniquely identifying the event in this process. Clean up the event and release from memory Destroy cleans up the low-level resources allocated for this event and releases the event instance from memory. Create Reset the event ResetEvent turns off the event. Any WaitFor operation will suspend the calling thread. SetEvent WaitFor Set the event SetEvent sets the event. If the ManualReset is True any thread that was waiting for the event to be set (using WaitFor) will resume it's operation. After the event was set, any thread that executes WaitFor will return at once. If ManualReset is False, only one thread will be notified that the event was set, and the event will be immediatly reset after that. WaitFor ManualReset Wait for the event to be set.

WaitFor should be used in threads that should be notified when the event is set. When WaitFor is called, and the event is not set, the thread will be suspended. As soon as the event is set by some other thread (using SetEvent) or the timeout period (TimeOut) has expired, the WaitFor function returns. The return value depends on the condition that caused the WaitFor function to return.

The calling thread will wait indefinitely when the constant INFINITE is specified for the TimeOut parameter.

Reason for returning Maximum time to wait for the event to be set Should the event be reset manually Alias for TEventObject TEvent is a simple alias for the class. Simple, anonymous event TSimpleEvent is a simple descendent of the class. It creates an event with no name, which must be reset manually, and which is initially not set. Creates a new TSimpleEvent instance Create instantiates a new TSimpleEvent instance. It simply calls the inherited Create with Nil for the security attributes, an empty name, AManualReset set to True, and InitialState to False. Try and obtain the critical section TryEnter tries to enter the critical section: it returns at once and does not wait if the critical section is owned by another thread; if the current thread owns the critical section or the critical section was obtained successfully, true is returned. If the critical section is currently owned by another thread, False is returned. None. False if another thread owns the critical section, true if obtained at once.