Class SharedMemory

java.lang.Object

org.newsclub.net.unix.memory.SharedMemory

All Implemented Interfaces:

Closeable, AutoCloseable

public final class SharedMemory
extends Object
implements Closeable

Some shared memory.

Author:

Christian Kohlschütter

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MUTEX_SEGMENT_SIZE	The exact size (in bytes) required for a MemorySegment used in mutex(MemorySegment).

Method Summary

Modifier and Type	Method	Description
void	addSeals(Set<MemorySeal> seals)	Adds the given MemorySeals, preventing certain operations on shared memory.
MemorySegment	asMappedMemorySegment(FileChannel.MapMode mapMode)	Return a MemorySegment instance corresponding to this shared memory object, using the given FileChannel.MapMode, and a custom shared Arena that will be closed upon close().
MemorySegment	asMappedMemorySegment(FileChannel.MapMode mapMode, Arena arena)	Return a MemorySegment instance corresponding to this shared memory object, using the given FileChannel.MapMode, and the given arena.
MemorySegment	asMappedMemorySegment(FileChannel.MapMode mapMode, Arena arena, int duplicates)	Return a MemorySegment instance corresponding to this shared memory object -- repeated multiple times after each other (aligned with page size) -- using the given FileChannel.MapMode, and the given arena, as well as the duplication count.
MemorySegment	asMappedMemorySegment(FileChannel.MapMode mapMode, Arena arena, long offset, long length, int duplicates)	Return a MemorySegment instance corresponding to a range of this shared memory object -- repeated multiple times after each other (aligned with page size) -- using the given FileChannel.MapMode, and the given arena, as well as the duplication count.
long	byteSize()	Returns the aligned size of this shared memory instance.
void	close()	Closes this SharedMemory resource, potentially unlinking the corresponding underlying resource from the kernel if the object has been instantiated with SharedMemoryOption.UNLINK_UPON_CLOSE.
static SharedMemory	createAnonymous(long minimumLength)	Creates a new SharedMemory instance using an anonymous identifier.
static SharedMemory	createAnonymous(long minimumLength, SharedMemoryOption... options)	Creates a new SharedMemory instance using an anonymous identifier.
static SharedMemory	createExclusively(String name, long minimumLength, Set<PosixFilePermission> perms, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name.
static SharedMemory	createExclusively(String name, long minimumLength, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable).
static SharedMemory	createOrOpenExisting(String name, long minimumLength, Set<PosixFilePermission> perms, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given namex.
static SharedMemory	createOrOpenExisting(String name, long minimumLength, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable).
static SharedMemory	createOrReuseExisting(String name, long minimumLength, Set<PosixFilePermission> perms, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name.
static SharedMemory	createOrReuseExisting(String name, long minimumLength, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable).
static long	defaultAllocationSize()	Returns the system's default memory page allocation size for shared memory.
FileDescriptor	getFileDescriptor()	Returns the file descriptor associated with this instance.
Set<MemorySeal>	getSeals()	Returns the current MemorySeals for this shared memory instance.
static void	init(MemoryImplUtilInternal util)	Internal initializer used by junixsocket-common; do not use.
SharedMutex	mutex(MemorySegment addr)	Returns a SharedMutex instance working with the given MemorySegment, which has to be exactly MUTEX_SEGMENT_SIZE bytes long.
static SharedMemory	openExisting(String name, SharedMemoryOption... options)	Creates a new SharedMemory instance under the given name, using the object under the given name.
static void	unlinkShared(String name)	Asks to explicitly unlink/remove a shared memory object identified by the given name.
static SharedMemory	using(FileDescriptor fd)	Creates a new SharedMemory instance using the given file descriptor, which can be associated with a regular file that is to be memory-mapped, or a shared memory region.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MUTEX_SEGMENT_SIZE

public static final int MUTEX_SEGMENT_SIZE

The exact size (in bytes) required for a MemorySegment used in mutex(MemorySegment).

See Also:

• Constant Field Values

Method Details

init

public static void init(MemoryImplUtilInternal util)

Internal initializer used by junixsocket-common; do not use.

Parameters:

util - The MemoryImplUtil instance.

using

public static SharedMemory using(FileDescriptor fd)
                          throws IOException

Creates a new SharedMemory instance using the given file descriptor, which can be associated with a regular file that is to be memory-mapped, or a shared memory region.

Parameters:

fd - The file descriptor.

Returns:

The new instance.

Throws:

IOException - on error.

createExclusively

public static SharedMemory createExclusively(String name,
 long minimumLength,
 SharedMemoryOption... options)
                                      throws IOException

Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable). If there already exists an object under that name, this call fails with an error.

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createExclusively

public static SharedMemory createExclusively(String name,
 long minimumLength,
 Set<PosixFilePermission> perms,
 SharedMemoryOption... options)
                                      throws IOException

Creates a new SharedMemory instance under the given name. If there already exists an instance under that name, this call fails with an error.

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

perms - The file system permissions, where applicable.

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createOrOpenExisting

public static SharedMemory createOrOpenExisting(String name,
 long minimumLength,
 SharedMemoryOption... options)
                                         throws IOException

Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable). If there already exists an object under that name, that object is opened instead.

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createOrOpenExisting

public static SharedMemory createOrOpenExisting(String name,
 long minimumLength,
 Set<PosixFilePermission> perms,
 SharedMemoryOption... options)
                                         throws IOException

Creates a new SharedMemory instance under the given namex. If there already exists an object under that name, that object is opened instead.

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

perms - The file system permissions, where applicable.

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createOrReuseExisting

public static SharedMemory createOrReuseExisting(String name,
 long minimumLength,
 SharedMemoryOption... options)
                                          throws IOException

Creates a new SharedMemory instance under the given name, using default permissions (read-write for all users, where applicable). If there already exists an object under that name, that object is reused (truncated to zero or deleted prior to allocation).

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createOrReuseExisting

public static SharedMemory createOrReuseExisting(String name,
 long minimumLength,
 Set<PosixFilePermission> perms,
 SharedMemoryOption... options)
                                          throws IOException

Creates a new SharedMemory instance under the given name. If there already exists an object under that name, that object is reused (truncated to zero or deleted prior to allocation).

Parameters:

name - The name.

minimumLength - The requested length (the actual object can be larger).

perms - The file system permissions, where applicable.

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

openExisting

public static SharedMemory openExisting(String name,
 SharedMemoryOption... options)
                                 throws IOException

Creates a new SharedMemory instance under the given name, using the object under the given name. This call fails with an exception if no such object exists.

Parameters:

name - The name.

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

createAnonymous

public static SharedMemory createAnonymous(long minimumLength)
                                    throws IOException

Creates a new SharedMemory instance using an anonymous identifier.

Parameters:

minimumLength - The requested length (the actual object can be larger).

Returns:

The new instance.

Throws:

IOException - on error.

createAnonymous

public static SharedMemory createAnonymous(long minimumLength,
 SharedMemoryOption... options)
                                    throws IOException

Creates a new SharedMemory instance using an anonymous identifier.

Parameters:

minimumLength - The requested length (the actual object can be larger).

options - Instantiation options.

Returns:

The new instance.

Throws:

IOException - on error.

unlinkShared

public static void unlinkShared(String name)
                         throws IOException

Asks to explicitly unlink/remove a shared memory object identified by the given name.

This call may silently fail (some platforms do not support explicit unlinking -- they cleanup the objects automatically).

Parameters:

name - The name of the object that should be unlinked.

Throws:

IOException - on error.

getFileDescriptor

public FileDescriptor getFileDescriptor()

Returns the file descriptor associated with this instance.

Returns:

The file descriptor.

asMappedMemorySegment

public MemorySegment asMappedMemorySegment(FileChannel.MapMode mapMode)
                                    throws IOException

Return a MemorySegment instance corresponding to this shared memory object, using the given FileChannel.MapMode, and a custom shared Arena that will be closed upon close().

Parameters:

mapMode - The map mode.

Returns:

The memory segment.

Throws:

IOException - on error.

asMappedMemorySegment

public MemorySegment asMappedMemorySegment(FileChannel.MapMode mapMode,
 Arena arena)
                                    throws IOException

Return a MemorySegment instance corresponding to this shared memory object, using the given FileChannel.MapMode, and the given arena.

If the given arena is null, a custom shared Arena is used that will be closed upon close().

Parameters:

mapMode - The map mode.

arena - The arena to use, or null.

Returns:

The memory segment.

Throws:

IOException - on error.

asMappedMemorySegment

public MemorySegment asMappedMemorySegment(FileChannel.MapMode mapMode,
 Arena arena,
 int duplicates)
                                    throws IOException

Return a MemorySegment instance corresponding to this shared memory object -- repeated multiple times after each other (aligned with page size) -- using the given FileChannel.MapMode, and the given arena, as well as the duplication count.

This method is particularly useful to simplify building circular buffers ("magic RingBuffer").

If the given arena is null, a custom shared Arena is used that will be closed upon close().

Parameters:

mapMode - The map mode.

arena - The arena to use, or null.

duplicates - The number of times the shared memory should be repeated (0 = no repetitions, just 1 copy).

Returns:

The memory segment.

Throws:

IOException - on error.

asMappedMemorySegment

public MemorySegment asMappedMemorySegment(FileChannel.MapMode mapMode,
 Arena arena,
 long offset,
 long length,
 int duplicates)
                                    throws IOException

Return a MemorySegment instance corresponding to a range of this shared memory object -- repeated multiple times after each other (aligned with page size) -- using the given FileChannel.MapMode, and the given arena, as well as the duplication count.

This method is particularly useful to simplify building circular buffers ("magic RingBuffer").

If the given arena is null, a custom shared Arena is used that will be closed upon close().

Parameters:

mapMode - The map mode.

arena - The arena to use, or null.

offset - The offset from the beginning of this segment, in bytes.

length - The length of the mapped region, in bytes.

duplicates - The number of times the shared memory should be repeated (0 = no repetitions, just 1 copy).

Returns:

The memory segment.

Throws:

IOException - on error.

addSeals

public void addSeals(Set<MemorySeal> seals)
              throws IOException

Adds the given MemorySeals, preventing certain operations on shared memory.

Parameters:

seals - The seals.

Throws:

IOException - on error (e.g., if unsupported).

getSeals

public Set<MemorySeal> getSeals()
                         throws IOException

Returns the current MemorySeals for this shared memory instance.

Returns:

The seals, or empty if none or unsupported.

Throws:

IOException - on error (e.g., if a system call fails unexpectedly).

close

public void close()
           throws IOException

Closes this SharedMemory resource, potentially unlinking the corresponding underlying resource from the kernel if the object has been instantiated with SharedMemoryOption.UNLINK_UPON_CLOSE.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

defaultAllocationSize

public static long defaultAllocationSize()

Returns the system's default memory page allocation size for shared memory.

This may be larger than the system's regular page size (e.g., on Windows it's 64k).

Returns:

The page size.

mutex

public SharedMutex mutex(MemorySegment addr)
                  throws IOException

Returns a SharedMutex instance working with the given MemorySegment, which has to be exactly MUTEX_SEGMENT_SIZE bytes long.

Parameters:

addr - The address.

Returns:

The instance.

Throws:

IOException - on error.

byteSize

public long byteSize()

Returns the aligned size of this shared memory instance.

Returns:

The aligned size, in bytes.