Tcl Windows API extension

Synchronization

Commands related to synchronization primitives

SYNOPSIS

package require twapi_synch

create_event ?options?

create_mutex ?options?

lock_mutex HANDLE ?-wait MILLISECS?

open_mutex ?-access ACCESSRIGHTS? ?-inherit BOOLEAN?

reset_event HANDLE

set_event HANDLE

unlock_mutex HANDLE

DESCRIPTION

This package provides procedures related to various syncrhonization primitives on Windows platforms.

Mutexes

A mutex is a synchronization object that can be used to coordinate mutually exclusive access to shared resources. Refer to the Windows SDK for details about capabilities and use.

Mutexes can be created using create_mutex. Existing mutexes can be accessed using open_mutex. The commands lock_mutex and unlock_mutex can be used to gain and release ownership of the shared resource.

Events

An event is a synchronization object that can be in one of two states - signalled and non-signalled. It is useful for notifying a process or thread of the occurence of some event. Refer to the Windows SDK for details about usage.

Event objects can be created through create_event and their state changed using the commands set_event and reset_event. An application can wait on an event object to be signalled using the wait_on_handle command.

Commands

create_event ?options?

Creates an event object with the specified options and returns a handle to it. The following options control the event properties:

-existvar VARNAME	If specified, the command will set the variable VARNAME in the caller's context to 0 if the event was newly created and to 1 if the event already existed.
-inherit BOOLEAN	If specified as true, the handle will be inherited by child processes (default false).
-manualreset BOOLEAN	By default, events are automatically reset to a non-signalled state when a thread successfully waits on an event. If this option is specified as true, the event remains signalled until it is explicitly reset using the reset_event command. Default is false.
-name NAME	Specifies the name of the event. Events are unnamed by default.
-secd SECURITY_DESCRIPTOR	Specifies a security descriptor for the event object. By default, a null security descriptor is used.
-signalled BOOLEAN	If specified as true the event object is created in a signalled state. Default is false. This option must not be specified as true if the option -name is also specified.

The returned handle can be passed to set_event and reset_event to change the state of the event object. The application can wait for an event to be signalled by calling wait_on_handle. The handle must be closed when no longer needed by passing it to close_handle.

create_mutex ?options?

Creates a mutex object with the specified options and returns a handle to it. The following options control the mutex properties:

-inherit BOOLEAN	If specified as true, the handle will be inherited by child processes (default false).
-lock BOOLEAN	If specified as true the mutex is created in a locked state. Default is false. This option must not be specified as true if the option -name is also specified.
-name NAME	Specifies the name of the event. Events are unnamed by default.
-secd SECURITY_DESCRIPTOR	Specifies a security descriptor for the event object. By default, a null security descriptor is used.

The returned mutex handle can be passed to lock_mutex and unlock_mutex to claim or release ownership. The handle must be closed when no longer needed by passing it to close_handle.

lock_mutex HANDLE ?-wait MILLISECS?

Attempts to lock the mutex specified by HANDLE. Refer to wait_on_handle for possible return values and details about the -wait option.

open_mutex ?-access ACCESSRIGHTS? ?-inherit BOOLEAN?

Returns a handle to an existing mutex. The following options may be specfied:

-access ACCESSRIGHTS	Specifies a list of desired access rights. If this option is not specified, access rights default to mutex_all_access. See Access Rights for a description of the format of this list and for a description of standard access rights.
-inherit BOOLEAN	If specified as true, the handle will be inherited by child processes (default false).

The returned mutex handle can be passed to lock_mutex and unlock_mutex to claim or release ownership. The handle must be closed when no longer needed by passing it to close_handle.

reset_event HANDLE

Changes the state of the event object specified by HANDLE to be non-signalled.

set_event HANDLE

Changes the state of the event object specified by HANDLE to be signalled.