RU/2: Форум. Общение пользователей и разработчиков OS/2 (eCS). : Multithreading (XIII)

From	:	???
To	:	All
Subj	:	Multithreading (XIII)

The OS/2 APIs DosCreateMutexSem, DosRequestMutexSem, and DosReleaseMutexSem

1. DosCreateMutexSem

Prototype:

#define INCL_DOSSEMAPHORES
#include <os2.h>

APIRET DosCreteMutexSem(PSZ pszname, PHMTX phmtx, ULONG flAttr, BOOL32 fstate);

Syntax:

/* Creates a mutex semaphore. */

#define INCL_DOSSEMAPHORES
#include <os2.h>

PSZ pszName; /* Pointer to the ASCIIZ name of the semaphore. */
PHMTX phmtx; /* A pointer to the handle of the mutex semaphore. */
ULONG flAttr; /* A set of flags that specify the attributes of the semaphore. */
BOOL32 fState; /* Initial state of the semaphore. */
APIRET ulrc; /* Return Code. */

ulrc = DosCreateMutexSem(pszName, phmtx, flAttr, fState);

Parameters:

pszName (PSZ) - input : Pointer to the ASCIIZ name of the semaphore.

This is a pointer to a null terminated string with the name of the semaphore to create,
or NULL to create an unnamed semaphore. A semaphore name must(!) begin with the
prefix \SEM32\.

Semaphore names are validated by the file system, and must include the prefix \SEM32\.
A maximum of 255 characters is allowed. If these requirements are not met,
ERROR_INVALID_NAME is returned.
If the semaphore already exists, ERROR_DUPLICATE_NAME is returned.

If this field is null, the semaphore is unnamed. Unnamed mutex semaphores can be either
private or shared, depending on flAttr. They are identified by the semaphore handle that
phmtx points to.

By default, named semaphores are shared.

phmtx (PHMTX) - output : A pointer to the handle of the new mutex semaphore.

flAttr (ULONG) - input : A set of flags that specify the attributes of the semaphore.

If the DC_SEM_SHARED bit is set, the semaphore is shared. DC_SEM_SHAHRED makes an
unnamed semaphore shared. Otherwise, this flag should be set to 0L. This bit is checked
only if the semaphore is unnamed (that is, if pszName is null), because all named
semaphores are shared.

fState (BOOL32) - input : Initial state of the mutex semaphore.

Possible values are shown in the following list:

0 FALSE - The initial state of the semaphore is "unowned(not owned)."

1 TRUE - The initial state of the semaphore is "owned by the creating thread."

ulrc (APIRET) - returns : Return Code.

DosCreateMutexSem returns one of the following values:

0 - NO_ERROR
8 - ERROR_NOT_ENOUGH_MEMORY
87 - ERROR_INVALID_PARAMETER
123 - ERROR_INVALID_NAME
285 - ERROR_DUPLICATE_NAME
290 - ERROR_TOO_MANY_HANDLES

Remarks:

The DosCreateMutexSem() function creates a mutual exclusion(mutex) semaphore and
opens it for use by the current process. The semaphore can be either named or unnamed
depending on whether pszName specifies a string or is NULL.

A semaphore can be made accessible by the creator or other processes via a call to
DosOpenMutexSem(), although it is not necessary for the creator to explicitly open
the semaphore.

An unnamed semaphore can be created as shared by setting the DC_SEM_SHARED bit
in the flAttr parameter. Shared semaphores can be opened by processes other than the
creator.

Note that, because a shared, unnamed semaphore has no name, its handle must, in some
way, be made available by the creator to processes that need to use it.

All named semaphores are shared, so it is not necessary to explicitly set the
DC_SEM-SHARED bit when creating a named semaphore.

Example:

/* This example creates a named mutual exclusion (Mutex) semaphore, manipulates it,
and finally closes it.

#define INCL_DOSSEMAPHORES /* Semaphore values */
#define INCL_DOSERRORS /* DOS Error values */
#include <os2.h>
#include <stdio.h>

int main(VOID) {

HMTX hmtx = NULLHANDLE; /* Mutex semaphore handle */
PID pidOwner = 0; /* PID of current mutex semaphore owner */
TID tidOwner = 0; /* TID of current mutex semaphore owner */
ULONG ulCount = 0; /* Request count for the semaphore */
APIRET rc = NO_ERROR; /* Return code */

rc = DosCreateMutexSem("\\SEM32\\MUTEX1", /* Semaphore name */
&hmtx, 0, FALSE); /* Handle returned */

if (rc != NO_ERROR) {
printf("DosOpenMutexSem error: return code = %u\n", rc);
return 1;
}

/* This would normally be done by another unit of work */

rc = DosOpenMutexSem("\\SEM32\\MUTEX1", /* Semaphore name */
&hmtx); /* Handle returned */

if (rc != NO_ERROR) {
printf("DosOpenMutexSem error: return code = %u\n", rc);
return 1;
}

rc = DosRequestMutexSem(hmtx, /* Handle of semaphore */
(ULONG) SEM_INDEFINITE_WAIT); /* Timeout (none) */

if (rc != NO_ERROR) {
printf("DosRequestMutexSem error: return code = %u\n", rc);
return 1;
}

rc = DosQueryMutexSem(hmtx, /* Handle of semaphore */
&pidOwner, /* Process ID of owner */
&tidOwner, /* Thread ID of owner */
&ulCount); /* Count */

if (rc != NO_ERROR) {
printf("DosQueryMutexSem error: return code = %u\n", rc);
return 1;
} else {

printf("Semaphore owned by PID %u, TID %u.", pidOwner, tidOwner);
printf(" Request count is %u.\n", ulCount);
} /* endif */

rc = DosReleaseMutexSem(hmtx); /* Relinquish ownership */

if (rc != NO_ERROR) {
printf("DosReleaseMutexSem error: return code = %u\n", rc);
return 1;
}

rc = DosCloseMutexSem(hmtx); /* Close mutex semaphore */

if (rc != NO_ERROR) {
printf("DosCloseMutexSem error: return code = %u\n", rc);
return 1;
}

return NO_ERROR;
}

2. DosRequestMutexSem

Prototype

#define INCL_DOSSEMHORES
#include <os2.h>

APIRET DosRequestMutexSem(HTMX htmx, ULONG ulTimeout);

Syntax

/* Requests ownership of a mutex semaphore. */

#define INCL_DOSSEMAPHORES
#include <os2.h>

HMTX hmtx; /* The handle of the mutex semaphore to request. */
ULONG ulTimeout; /* The time-out in milliseconds. */
APIRET ulrc; /* Return Code. */

ulrc = DosRequestMutexSem(hmtx, ulTimeout);

Parameters

hmtx (HMTX) - input : The handle of the mutex semaphore being requested.

ulTimeout (ULONG) - input: The time-out in milliseconds.

This is the maximum amount of time the user wants to allow the thread to be blocked.

his parameter can also have the following values:

0L - SEM_IMMEDIATE_RETURN

DosRequestMutexSem returns immediately without blocking the calling thread.

-1L - SEM_INDEFINITE_WAIT

DosRequestMutexSem blocks the calling thread indefinitely.

ulrc (APIRET) - returns : Return Code.

DosRequestMutexSem returns one of the following values:

0 - NO_ERROR
6 - ERROR_INVALID_HANDLE
95 - ERROR_INTERRUPT
103 - ERROR_TOO_MANY_SEM_REQUESTS
105 - ERROR_SEM_OWNER_DIED
640 - ERROR_TIMEOUT

Example: see the example above

Remarks:

This function is called to request the ownership of a mutual exclusion(mutex) semaphore.
The ownership is relinquished via a call to DosReleaseMutxSem().

Calls to DosRequestMutexSem() can be nested: a count is kept of the number of times
that DosRequestMutexSem() has been called by the owning thread, and that number of
calls to DosReleaseMutexSem() are required before another thread will be granted
ownership.

This function can be called by any thread in the process that created the semaphore.
Threads in other processes can also call thsi function, but they must first gain access
to the semaphore by issuing the function DosOpenMutexSem().

Unless SEM_IMMEDIATE_RETURN is specified, this call will block until ownership can be
passed to the current thread. If a timeout is specified, the call will return with an error
if the timeout elapses before ownership can be obtained.

3. DosReLeaseMutexSem

Prototype

#define INCL_DOSSEMAPHORES
#include <os2.h>

APIRET DosReleaseMutexSem(HMTX hmtx);

Syntax

/* Relinquishes ownership of a mutex semaphore. */

#define INCL_DOSSEMAPHORES
#include <os2.h>

HMTX hmtx; /* The handle of the mutex semaphore to release. */
APIRET ulrc; /* Return Code. */

ulrc = DosReleaseMutexSem(hmtx);

Parameters

hmtx (HMTX) - input : The handle of the mutex semaphore to release.

ulrc (APIRET) - returns : Return Code.

DosReleaseMutexSem returns one of the following values:

0 - NO_ERROR
6 - ERROR_INVALID_HANDLE
288 - ERROR_NOT_OWNER

Remarks

The function DosReleaseMutexSem() releases the ownership of a mutual exclision(mutex)
semaphore that was requested by the DosrequestMutexSem() function.

If multiple calls have been started to DosRequestMutexSem() by the owned thread, then
the same number of calls are required to DosReleaseMutexSem() to fully release the
semaphore.

Note that this call can be issued only by the thread that owns the mutex semaphore.

Example: See the exmaple above.

Sun 01 Feb 2004 17:47

Mozilla/4.61 [en] (OS/2; U)

Multithreading (XIII) (???, 01.02.04 17:47)

Список сообщений \| Написать новое \| Ответить на сообщение \| Домой	Поиск:
Предыдущее сообщение \| Следующее сообщение