| Navigation: Advanced Topics > Thread Model Documentation > Multi-Threading Programming >====== Summary of Synchronization Objects Properties and Methods ====== |    |
The following section provides a quick summary description of the common properties and methods used with the Synchronization Objects discussed previously.
Prototypes
Note: The following prototypes can be found in CWSYNCHM.INC
GetMutex( name, <;error> )
| name | A string constant or variable that names the IMutex object. |
| Error | A LONG variable that returns any operating system error. |
Purpose:
Returns a reference to an IMutex for a Mutex that has already been created with NewMutex( )
If the Mutex has not been previously created, a NULL is returned.
Example:
MySem &IMutex
CODE
MySem &= GetMutex('MyApp_RequestServer')
IF MySem &= NULL
MESSAGE('Server not running')
RETURN(False)
END
GetSemaphore( name, <;error> )
| name | A string constant or variable that names the ISemaphore object. |
| Err | A LONG variable that returns any operating system error. |
Purpose:
Returns a reference to an ISemaphore for a semaphore that has already been created with NewNamedSemaphore( )
If the semaphore has not been previously created, a NULL is returned.
Example:
MySem &ISemaphore
CODE
MySem &= GetSemaphore('MyApp_RequestServer')
IF MySem &= NULL
MESSAGE('Server not running')
RETURN(False)
END
NewCriticalSection ()
Purpose:
Returns a reference to a new ICriticalSection
Example:
! This code is invoked for every started thread before call to ThreadProc.
! Depending on the current thread, Action.Construct executes one of 3
! handler procedures.
Action.Construct PROCEDURE()
CODE
SELF.Threadno = THREAD()
CASE SELF.ThreadNo
OF 1
Sync &= NewCriticalSection() ! Create the critical section object
MainThread &= SELF ! Set MainThread to instance of Action
! for the main thread
FrameProc (SELF)
MainThread &= NULL
Sync.Kill() ! Delete the critical section
OF 2
ToolThread &= SELF ! Set ToolThread to instance of Action
! for the toolbox's thread
ToolProc (SELF)
ToolThread &= NULL
ELSE
ChildProc (SELF)
END
RETURN
NewMutex( )
NewMutex(name, owner, <;error>)
| name | A string constant or variable that names the new IMutex object. If a name parameter is not supplied, NewMutex is used for synchronizing threads only. If a name is supplied, NewMutex can be used to synchronize multiple processes rather than just the threads within a process. |
| owner | A BYTE variable or constant that specifies the initial owner of the Mutex. If this value is TRUE, and the caller creates the Mutex, the calling thread obtains ownership of the Mutex. This is the equivalent of calling Mutex.Wait immediately after NewMutex(). If the caller did not create the mutex, then the calling thread does not obtain ownership of the Mutex. To determine if the caller created the Mutex, you need to check the value of Err |
| error | A LONG variable or constant that returns any operating system error. ERROR_ALREADY_EXISTS (183) indicates that the caller did not create the Mutex (a handle is still returned but owner is ignored) because another process or thread has already created the Mutex. |
Purpose:
Returns a reference to a new IMutex. If the Mutex could not be created, a Null value will be returned. Check the Error parameter for the reason. (Some reasons for failure can be that another object (e.g., semaphore) exists with the same name, or a different user has created the object (e.g., security error)).
NewNamedSemaphore (name, initial, max , <;error> )
| name | A string constant or variable that names the new ISemaphore object. |
| initial | A LONG variable or constant that indicates the maximum number of threads that can access the semaphore. The default value is zero. |
| max | A LONG variable or constant that indicates the maximum number of threads that can simultaneously access the semaphore. |
| error | A LONG variable that returns any operating system error. An ERROR_ALREADY_EXISTS (183) error indicates that another process or thread has already created the Mutex. |
Purpose:
Returns a reference to a new ISemaphore. This semaphore can be used for synchronizing threads or processes. If an ERROR_ALREADY_EXISTS (183) is posted to error, then the Semaphore already existed, and initial and max are ignored.
Using the default settings, NewNamedSemaphore will create a semaphore that no threads can wait on until someone calls a Release.
NewReaderWriterLock ( WritersHavePriority)
| WritersHavePriority | A BYTE variable or constant that sets priority of the Writer. |
Purpose:
Returns a reference to a new IreaderWriterLock
If WritersHavePriority is TRUE, a Writer waiting for ownership of the ReaderWriterLock object will take priority over any Readers that are waiting for ownership.
If WritersHavePriority is FALSE, all Readers waiting for ownership of the ReaderWriterLock object will take priority over any Writer waiting for ownership.
NewSemaphore ( initial , max)
| Initial | A LONG variable or constant that indicates the maximum number of threads that can access the semaphore. The default value is zero. |
| Max | A LONG variable or constant that indicates the maximum number of times that the semaphore can be owned. It is a maximum resource count. |
Purpose:
Returns a reference to a new ISemaphore
If initial is non-zero, then this indicates how many threads can initially and simultaneously have access to the semaphore
max indicates the maximum number of threads that can simultaneously access the semaphore. By default, this will create a semaphore that no threads can wait on until a Release is called.