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

---

Detailed Description

Shared Memory Semaphores.

#include <Windows.h>
#include <shlobj.h>
#include "hyport.h"
#include "portpriv.h"
#include "portnls.h"
#include "ut_hyprt.h"
#include "hyshmem.h"

Functions
IDATA VMCALL	hyshmem_open (struct HyPortLibrary *portLibrary, struct hyshmem_handle **handle, const char *rootname, I_32 size, I_32 perm)
	Creates/open a shared memory region.
void *VMCALL	hyshmem_attach (struct HyPortLibrary *portLibrary, struct hyshmem_handle *handle)
	Attaches the shared memory represented by the handle.
IDATA VMCALL	hyshmem_detach (struct HyPortLibrary *portLibrary, struct hyshmem_handle **handle)
	Detaches the shared memory region from the caller's process address space Use hyshmem_destroy to actually remove the memory region from the Operating system.
IDATA VMCALL	hyshmem_destroy (struct HyPortLibrary *portLibrary, struct hyshmem_handle **handle)
	Destroy and removes the shared memory region from OS.
void VMCALL	hyshmem_shutdown (struct HyPortLibrary *portLibrary)
	PortLibrary shutdown.
I_32 VMCALL	hyshmem_startup (struct HyPortLibrary *portLibrary)
	PortLibrary startup.
void VMCALL	hyshmem_close (struct HyPortLibrary *portLibrary, struct hyshmem_handle **handle)
	Detach, Close and remove the shared memory handle.
void VMCALL	hyshmem_findclose (struct HyPortLibrary *portLibrary, UDATA findhandle)
	Close the handle returned from hyshmem_findfirst.
UDATA VMCALL	hyshmem_findfirst (struct HyPortLibrary *portLibrary, char *resultbuf)
	Find the name of a shared memory region on the system.
I_32 VMCALL	hyshmem_findnext (struct HyPortLibrary *portLibrary, UDATA findHandle, char *resultbuf)
	Find the name of the next shared memory region.
UDATA VMCALL	hyshmem_stat (struct HyPortLibrary *portLibrary, const char *name, struct HyPortShmemStatistic *statbuf)
	Return the statistic for a shared memory region.

---

Function Documentation

void* VMCALL hyshmem_attach	(	struct HyPortLibrary *	portLibrary,
		struct hyshmem_handle *	handle
	)

Attaches the shared memory represented by the handle.

Parameters:

[in]	portLibrary	The port Library
[in]	handle	A valid shared memory handle

Returns:

: A pointer to the shared memory region, NULL on failure

void VMCALL hyshmem_close	(	struct HyPortLibrary *	portLibrary,
		struct hyshmem_handle **	handle
	)

Detach, Close and remove the shared memory handle.

Note:

This method does not remove the shared memory region from the OS use hyshmem_destroy instead. However this will free all the memory resources used by the handle, and detach the region specified by the handle

Parameters:

[in]	portLibrary	The port Library
[in]	handle	Pointer to a valid shared memory handle

IDATA VMCALL hyshmem_destroy	(	struct HyPortLibrary *	portLibrary,
		struct hyshmem_handle **	handle
	)

Destroy and removes the shared memory region from OS.

The timing of which OS removes the memory is OS dependent. However when you make a call you can considered that you can no longer access the region through the handle. Memory allocated for handle structure is freed as well.

Parameters:

[in]	portLibrary	The port Library
[in]	handle	Pointer to a valid shared memory handle

Returns:

0 on success, -1 on failure.

IDATA VMCALL hyshmem_detach	(	struct HyPortLibrary *	portLibrary,
		struct hyshmem_handle **	handle
	)

Detaches the shared memory region from the caller's process address space Use hyshmem_destroy to actually remove the memory region from the Operating system.

Parameters:

[in]	portLibrary	the Port Library.
[in]	handle	Pointer to the shared memory region.

Returns:

0 on success, -1 on failure.

void VMCALL hyshmem_findclose	(	struct HyPortLibrary *	portLibrary,
		UDATA	findhandle
	)

Close the handle returned from hyshmem_findfirst.

Parameters:

[in]	portLibrary	The port library
[in]	findhandle	Handle returned from hyshmem_findfirst.

UDATA VMCALL hyshmem_findfirst	(	struct HyPortLibrary *	portLibrary,
		char *	resultbuf
	)

Find the name of a shared memory region on the system.

Answers a handle to be used in subsequent calls to hyshmem_findnext and hyshmem_findclose.

Parameters:

[in]	portLibrary	The port library
[out]	resultbuf	filename and path matching path.

Returns:

valid handle on success, -1 on failure.

I_32 VMCALL hyshmem_findnext	(	struct HyPortLibrary *	portLibrary,
		UDATA	findHandle,
		char *	resultbuf
	)

Find the name of the next shared memory region.

Parameters:

[in]	portLibrary	The port library
[in]	findHandle	handle returned from hyshmem_findfirst.
[out]	resultbuf	next filename and path matching findhandle.

Returns:

0 on success, -1 on failure or if no matching entries.

IDATA VMCALL hyshmem_open	(	struct HyPortLibrary *	portLibrary,
		struct hyshmem_handle **	handle,
		const char *	rootname,
		I_32	size,
		I_32	perm
	)

Creates/open a shared memory region.

The rootname will uniquely identify the shared memory region, and is valid across different JVM instance.

The shared memory region should persist across process, until OS reboots or destroy call is being made.

Parameters:

[in]	portLibrary	The port Library
[out]	handle	This handle is required for further attach/destroy of the memory region
[in]	rootname	Shared name for the region, which used to identify the region.
[in]	size	Size of the region in bytes
[in]	perm	permission for the region.

Returns:

• HYPORT_ERROR_SHMEM_OPFAILED Failure - Cannot open the shared memory region
• HYPORT_INFO_SHMEM_OPENED Success - Existing memory region has been opened
• HYPORT_INFO_SHMEM_CREATED Success - A new shared memory region has been created

void VMCALL hyshmem_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 hyshmem_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_SHMEM

Note:

Most implementations will simply return success.

UDATA VMCALL hyshmem_stat	(	struct HyPortLibrary *	portLibrary,
		const char *	name,
		struct HyPortShmemStatistic *	statbuf
	)

Return the statistic for a shared memory region.

Note:

notice that the implementation can decided to put -1 in the fields of statbuf if it does not make sense on this platform, or it is impossible to obtain.

Parameters:

[in]	portLibrary	The port library
[in]	name	The name of the shared memory area.
[out]	statbuf	the statistics returns by the operating system

Returns:

0 on success, -1 on failure or if there is no matching entries.

---