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

---

Detailed Description

Shared Semaphores.

#include <Windows.h>
#include "hyport.h"
#include "portpriv.h"
#include "ut_hyprt.h"
#include "hyshsem.h"

Functions
IDATA VMCALL	hyshsem_open (struct HyPortLibrary *portLibrary, struct hyshsem_handle **handle, const char *semname, int setSize, int permission)
	Open an existing semaphore set, or create a new one if it does not exist.
IDATA VMCALL	hyshsem_post (struct HyPortLibrary *portLibrary, struct hyshsem_handle *handle, UDATA semset, UDATA flag)
	post operation increments the counter in the semaphore by 1 if there is no one in wait for the semaphore.
IDATA VMCALL	hyshsem_wait (struct HyPortLibrary *portLibrary, struct hyshsem_handle *handle, UDATA semset, UDATA flag)
	Wait operation decrements the counter in the semaphore set if the counter > 0 if counter == 0 then the caller will be suspended.
IDATA VMCALL	hyshsem_getVal (struct HyPortLibrary *portLibrary, struct hyshsem_handle *handle, UDATA semset)
	reading the value of the semaphore in the set.
IDATA VMCALL	hyshsem_setVal (struct HyPortLibrary *portLibrary, struct hyshsem_handle *handle, UDATA semset, IDATA value)
	setting the value of the semaphore specified in semset.
void VMCALL	hyshsem_close (struct HyPortLibrary *portLibrary, struct hyshsem_handle **handle)
	Release the resources allocated for the semaphore handles.
IDATA VMCALL	hyshsem_destroy (struct HyPortLibrary *portLibrary, struct hyshsem_handle **handle)
	Destroy the semaphore and release the resources allocated for the semaphore handles.
I_32 VMCALL	hyshsem_startup (struct HyPortLibrary *portLibrary)
	PortLibrary startup.
void VMCALL	hyshsem_shutdown (struct HyPortLibrary *portLibrary)
	PortLibrary shutdown.

---

Function Documentation

void VMCALL hyshsem_close	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle **	handle
	)

Release the resources allocated for the semaphore handles.

Parameters:

[in]	portLibrary	The port library.
[in]	handle	Semaphore set handle.

Note:

The actual semaphore is not destroyed. Once the close operation has been performed on the semaphore handle, it is no longer valid and user needs to reissue hyshsem_open call.

IDATA VMCALL hyshsem_destroy	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle **	handle
	)

Destroy the semaphore and release the resources allocated for the semaphore handles.

Parameters:

[in]	portLibrary	The port library.
[in]	handle	Semaphore set handle.

Returns:

0 on success, -1 on failure.

Note:

Due to operating system restriction we may not be able to destroy the semaphore

IDATA VMCALL hyshsem_getVal	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle *	handle,
		UDATA	semset
	)

reading the value of the semaphore in the set.

This function uses no synchronisation prmitives

Precondition:

caller has to deal with synchronisation issue.

Parameters:

[in]	portLibrary	The port library.
[in]	handle	Semaphore set handle.
[in]	semset	The number of semaphore in the semaphore set that you want to post.

Returns:

-1 on failure, the value of the semaphore on success

Warning:

: The user will need to make sure locking is done correctly when accessing semaphore values. This is because getValue simply reads the semaphore value without stopping the access to the semaphore. Therefore the value of the semaphore can change before the function returns.

IDATA VMCALL hyshsem_open	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle **	handle,
		const char *	semname,
		int	setSize,
		int	permission
	)

Open an existing semaphore set, or create a new one if it does not exist.

Parameters:

[in]	portLibrary	The port library.
[out]	handle	A semaphore handle is allocated and initialised for use with further calls, NULL on failure.
[in]	semname	Unique identifier of the semaphore.
[in]	setSize	Size of the semaphore set.
[in]	permission	Permission to the semaphore set.

Returns:

• HYPORT_ERROR_SHSEM_OPFAILED Failure - Error opening the semaphore
• HYPORT_INFO_SHSEM_CREATED Success - Semaphore has been created
• HYPORT_INFO_SHSEM_OPENED Success - Existing semaphore has been opened
• HYPORT_INFO_SHSEM_SEMID_DIFF Success - Existing semaphore opened, but OS Semaphore key is different

IDATA VMCALL hyshsem_post	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle *	handle,
		UDATA	semset,
		UDATA	flag
	)

post operation increments the counter in the semaphore by 1 if there is no one in wait for the semaphore.

if there are other processes suspended by wait then one of them will become runnable and the counter remains the same.

Parameters:

[in]	portLibrary	The port library.
[in]	handle	Semaphore set handle.
[in]	semset	The no of semaphore in the semaphore set that you want to post.
[in]	flag	The semaphore operation flag: HYPORT_SHSEM_MODE_DEFAULT The default operation flag, same as 0 HYPORT_SHSEM_MODE_UNDO The changes made to the semaphore will be undone when this process finishes.

Returns:

0 on success, -1 on failure.

IDATA VMCALL hyshsem_setVal	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle *	handle,
		UDATA	semset,
		IDATA	value
	)

setting the value of the semaphore specified in semset.

This function uses no synchronisation prmitives

Precondition:

Caller has to deal with synchronisation issue.

Parameters:

[in]	portLibrary	The port Library.
[in]	handle	Semaphore set handle.
[in]	semset	The no of semaphore in the semaphore set that you want to post.
[in]	value	The value that you want to set the semaphore to

Warning:

The user will need to make sure locking is done correctly when accessing semaphore values. This is because setValue simply set the semaphore value without stopping the access to the semaphore. Therefore the value of the semaphore can change before the function returns.

Returns:

0 on success, -1 on failure.

void VMCALL hyshsem_shutdown

(

struct HyPortLibrary *

portLibrary

)

PortLibrary shutdown.

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

Parameters:

[in]

portLibrary

The port library.

Note:

Most implementations will be empty.

I_32 VMCALL hyshsem_startup

(

struct HyPortLibrary *

portLibrary

)

PortLibrary startup.

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

Parameters:

[in]

portLibrary

The port library.

Returns:

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

• HYPORT_ERROR_STARTUP_SHSEM

Note:

Most implementations will simply return success.

IDATA VMCALL hyshsem_wait	(	struct HyPortLibrary *	portLibrary,
		struct hyshsem_handle *	handle,
		UDATA	semset,
		UDATA	flag
	)

Wait operation decrements the counter in the semaphore set if the counter > 0 if counter == 0 then the caller will be suspended.

Parameters:

[in]	portLibrary	The port library.
[in]	handle	Semaphore set handle.
[in]	semset	The no of semaphore in the semaphore set that you want to post.
[in]	flag	The semaphore operation flag: HYPORT_SHSEM_MODE_DEFAULT The default operation flag, same as 0 HYPORT_SHSEM_MODE_UNDO The changes made to the semaphore will be undone when this process finishes. HYPORT_SHSEM_MODE_NOWAIT The caller will not be suspended if sem == 0, a -1 is returned instead.

Returns:

0 on success, -1 on failure.

---