RU/2: Форум. Общение пользователей и разработчиков OS/2 (eCS). : Ответить на сообщение
Имя:
e-mail:
FIDO:
Home page:
сохранить данные о вас
Тема:
> 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. > > > > > > > > > > > > > > > > > > > > > >
_, _, _, _, _ _, _,_
(_ | / \ |\ | / \ |_/
, ) | , \ / | \| \ / | \
~ ~~~ ~ ~ ~ ~ ~ ~
Programmed by
Dmitri Maximovich
,
Dmitry I. Platonoff
,
Eugen Kuleshov
.
25.09.99 (c) 1999,
RU/2
. All rights reserved.
Rewritten by
Dmitry Ban
. All rights ignored.