Threads, Thread Safety, and Idling

These procedures provide a limited set of threading functionality, currently entirely directed at maintaining thread safety between the graphical user interface thread and the main program thread. All callbacks, or functions triggered by clicking a button, menu, or similar graphical control, are executed on the graphical user interface thread, while the main program runs on its own thread, generally speaking. If the main program or these callbacks perform memory allocations or array resizing, mutual exclusions, or mutexes, are recommended to ensure only one thread is modifying memory at a time.

Idling routines allow the main program thread to pause and wait for certain events to occur. For example, if user input is requested, a program might call loop to sit and wait for a menu item to be clicked. Once the item is clicked, callback function associated with that menu item could set a certain flag and call stopidle to allow the main program to proceed based on the flag set by the menu being clicked. Idling is preferable to, for example, looping infinitely using pure Fortran because it does not consume CPU resources while doing so.

createmutex

C int createmutex ( )
Fortran function createmutex ( )

Description

Creates a mutual exclusion for locking and unlocking access to variables from different threads.

Return Value

C int
Fortran integer

Unique identifier of the mutex

delay

C void delay (wait)
Fortran subroutine delay (wait)

Description

Delays, or sleeps, the program for the specified number of milliseconds.

Parameters

Parameter	C Type	Fortran Type	Description
wait	int	integer	The number of milliseconds to wait

lockmutex

C bool lockmutex (id, wait)
Fortran function lockmutex (id, wait)

Description

Attempts to lock a specified mutual exclusion, waiting for the specified number of milliseconds for access.

Parameters

Parameter	C Type	Fortran Type	Description
id	int	integer	The id of the mutex
wait	long	integer1	The number of milliseconds to wait for locking to occur. Negative or absense of the parameter will mean waiting forever

Return Value

C bool
Fortran logical

True if the mutex was successfully locked in the specified waiting period, false otherwise

loop

C void loop ( )
Fortran subroutine loop ( )

Description

Idles the main program thread for an infinite amount of time while allowing the graphical user interface to continue processing events. The idling state can be exited if the procedure stopidle is called, usually via a callback from a menu or button.

startidle

C void startidle (wait)
Fortran subroutine startidle (wait)

Description

Idles the main program thread for aspecified amount of time while allowing the graphical user interface to continue processing events. The idling state can be exited if the procedure stopidle is called, usually via a callback from a menu or button. If stopidle is not explicitly called, the function will return after the specified number of milliseconds has elapsed.

Parameters

Parameter	C Type	Fortran Type	Description
wait	long	integer	The number of milliseconds to wait in an idling state

stopidle

C void stopidle ( )
Fortran subroutine stopidle ( )

Description

Instructs the main program to exit the current idling state if currently idling. This routine is normally called from a graphical user interface element’s callback function to trigger the main program to continue execution after the event has been processed.

unlockmutex

C void unlockmutex (id)
Fortran subroutine unlockmutex (id)

Description

Unlocks and releases a mutual exclusion that was previously locked by the calling thread. Unlocking will allow other threads to lock the mutual exclusion.

Parameters

Parameter	C Type	Fortran Type	Description
id	long	integer	The identifier of the mutex to unlock

¹ Optional named argument