modules/portlib/src/main/native/port/windows/hyipcmutex.c File Reference

---

Detailed Description

Shared Resource Mutex.

The HYIPCMutex is used to protect a shared resource from simultaneous access by processes or threads executing in the same or different VMs. Each process/thread must request and wait for the ownership of the shared resource before it can use that resource. It must also release the ownership of the resource as soon as it has finished using it so that other processes competing for the same resource are not delayed.

#include <windows.h>
#include "hyport.h"

Functions
I_32 VMCALL	hyipcmutex_acquire (struct HyPortLibrary *portLibrary, const char *name)
	Acquires a named mutex for the calling process.
I_32 VMCALL	hyipcmutex_release (struct HyPortLibrary *portLibrary, const char *name)
	Releases a named Mutex from the calling process.
void VMCALL	hyipcmutex_shutdown (struct HyPortLibrary *portLibrary)
	PortLibrary shutdown.
I_32 VMCALL	hyipcmutex_startup (struct HyPortLibrary *portLibrary)
	PortLibrary startup.

---

Function Documentation

I_32 VMCALL hyipcmutex_acquire	(	struct HyPortLibrary *	portLibrary,
		const char *	name
	)

Acquires a named mutex for the calling process.

If a Mutex with the same Name already exists, the function opens the existing Mutex and tries to lock it. If another process already has the Mutex locked, the function will block indefinitely. If there is no Mutex with the same Name, the function will create it and lock it for the calling process of this function.

Parameters:

[in]	portLibrary	The port library
[in]	name	Mutex to be acquired

Returns:

0 on success, -1 on error.

Note:

The Mutex must be explicitly released by calling the hyipcmutex_release function as soon as the lock is no longer required.

I_32 VMCALL hyipcmutex_release	(	struct HyPortLibrary *	portLibrary,
		const char *	name
	)

Releases a named Mutex from the calling process.

If a Mutex with the same Name already exists, the function opens the existing Mutex and tries to unlock it. This function will fail if a Mutex with the given Name is not found or if the Mutex cannot be unlocked.

Parameters:

[in]	portLibrary	The port library
[in]	name	Mutex to be released.

Returns:

0 on success, -1 on error.

Note:

Callers of this function must have called the function hyipcmutex_acquire prior to calling this function.

void VMCALL hyipcmutex_shutdown

(

struct HyPortLibrary *

portLibrary

)

PortLibrary shutdown.

This function is called during shutdown of the portLibrary. Any resources that were created by hyipcmutex_startup should be destroyed here.

Parameters:

[in]

portLibrary

The port library

Note:

Most implementations will be empty.

I_32 VMCALL hyipcmutex_startup

(

struct HyPortLibrary *

portLibrary

)

PortLibrary startup.

This function is called during startup of the portLibrary. Any resources that are required for the IPC mutex operations may be created here. All resources created here should be destroyed in hyipcmutex_shutdown.

Parameters:

[in]

portLibrary

The port library

Returns:

0 on success, negative error code on failure. Error code values returned are

• HYPORT_ERROR_STARTUP_IPCMUTEX

Note:

Most implementations will simply return success.

---