Skip to content

Commit

Permalink
keep improving javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@carlosuc3m
carlosuc3m committed Dec 12, 2023
1 parent bcb3f00 commit 50689b3
Showing 1 changed file with 105 additions and 16 deletions.
121 changes: 105 additions & 16 deletions src/main/java/io/bioimage/modelrunner/tensor/shm/SharedMemoryArray.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,36 +32,92 @@
import net.imglib2.type.numeric.RealType;

/**
* Interface that contains the methods required to create or read Shared Memory Blocks for JDLL
* Interface to interact with shared memory segments retrieving the underlying information
*
* @author Carlos Garcia Lopez de Haro
*/
public interface SharedMemoryArray extends Closeable {


/**
* Constant to specify that the shared memory segment that is going to be open is only for
* reading
*/
public static final int O_RDONLY = 0;
public static final int O_RDWR = 2; // Read-write mode
public static final int O_CREAT = 64; // Create if it does not exist
public static final int PROT_READ = 0x1; // Page can be read
public static final int PROT_WRITE = 0x2; // Page can be written
public static final int MAP_SHARED = 0x01; // Share changes

/**
* Constant to specify that the shared memory segment that is going to be open is for
* reading and/or writing
*/
public static final int O_RDWR = 2;
/**
* Constant to specify that the shared memory segment that is going to be open will
* be created if it does not exist
*/
public static final int O_CREAT = 64;
/**
* Constant to specify that the shared memory regions mapped can be read but not written
*/
public static final int PROT_READ = 0x1;
/**
* Constant to specify that the shared memory regions mapped can be written
*/
public static final int PROT_WRITE = 0x2;
/**
* Constant to specify that the shared memory regions mapped can be shared with other processes
*/
public static final int MAP_SHARED = 0x01;
/**
* List of special characters that should not be used to name shared memory segments
*/
final static String[] SPECIAL_CHARS_LIST = new String[] {"/", "\\", "#", "·", "!", "¡", "¿", "?", "@", "|", "$", ">", "<", ";"};

/**
* This method copies the data from a {@link RandomAccessibleInterval} into a shared memory region
* to be able to shared it with other processes.
* An instance of {@link SharedMemoryArray} is created that helps managing the shared memory data.
* The name is assigned automatically.
*
* @param <T>
* possible ImgLib2 data types of the retrieved {@link RandomAccessibleInterval}
* @param rai
* the {@link RandomAccessibleInterval} that is going to be written into a shared memory region
* @return a {@link SharedMemoryArray} instance that helps handling the data written to the shared memory region
*/
static <T extends RealType<T> & NativeType<T>>
SharedMemoryArray buildSHMA(RandomAccessibleInterval<T> rai) {
if (PlatformDetection.isWindows()) return SharedMemoryArrayWin.build(rai);
else if (PlatformDetection.isLinux()) return SharedMemoryArrayLinux.build(rai);
else return SharedMemoryArrayMacOS.build(rai);
}


/**
* This method copies the data from a {@link RandomAccessibleInterval} into a shared memory region
* to be able to shared it with other processes.
* An instance of {@link SharedMemoryArray} is created that helps managing the shared memory data.
*
* @param <T>
* possible ImgLib2 data types of the retrieved {@link RandomAccessibleInterval}
* @param name
* name of the shared memory region where the {@link RandomAccessibleInterval} data has been copied
* @param rai
* the {@link RandomAccessibleInterval} that is going to be written into a shared memory region
* @return a {@link SharedMemoryArray} instance that helps handling the data written to the shared memory region
*/
static <T extends RealType<T> & NativeType<T>>
SharedMemoryArray buildSHMA(String name, RandomAccessibleInterval<T> rai) {
if (PlatformDetection.isWindows()) return SharedMemoryArrayWin.build(name, rai);
else if (PlatformDetection.isLinux()) return SharedMemoryArrayLinux.build(name, rai);
else return SharedMemoryArrayMacOS.build(name, rai);
}

/**
*
* @param <T>
* @param memoryName
* @param shape
* @param isFortran
* @param dataType
* @return
*/
static <T extends RealType<T> & NativeType<T>>
RandomAccessibleInterval<T> buildImgLib2FromSHMA(String memoryName, long[] shape, boolean isFortran, String dataType) {
if (PlatformDetection.isWindows())
Expand All @@ -72,6 +128,12 @@ else if (PlatformDetection.isLinux())
return SharedMemoryArrayMacOS.createImgLib2RaiFromSharedMemoryBlock(memoryName, shape, isFortran, dataType);
}

/**
*
* @param <T>
* @param memoryName
* @return
*/
static <T extends RealType<T> & NativeType<T>>
RandomAccessibleInterval<T> buildImgLib2FromNumpyLikeSHMA(String memoryName) {
if (PlatformDetection.isWindows())
Expand All @@ -81,7 +143,11 @@ else if (PlatformDetection.isLinux())
else
return SharedMemoryArrayMacOS.buildImgLib2FromNumpyLikeSHMA(memoryName);
}

/**
*
* @param memoryName
* @return
*/
static HashMap<String, Object> buildMapFromNumpyLikeSHMA(String memoryName) {
if (PlatformDetection.isWindows())
return SharedMemoryArrayWin.buildMapFromNumpyLikeSHMA(memoryName);
Expand All @@ -91,13 +157,26 @@ else if (PlatformDetection.isLinux())
return SharedMemoryArrayMacOS.buildMapFromNumpyLikeSHMA(memoryName);
}

/**
*
* @param <T>
* @param rai
* @return
*/
static <T extends RealType<T> & NativeType<T>>
SharedMemoryArray buildNumpyLikeSHMA(RandomAccessibleInterval<T> rai) {
if (PlatformDetection.isWindows()) return SharedMemoryArrayWin.buildNumpyFormat(rai);
else if (PlatformDetection.isLinux()) return SharedMemoryArrayLinux.buildNumpyFormat(rai);
else return SharedMemoryArrayMacOS.buildNumpyFormat(rai);
}

/**
*
* @param <T>
* @param name
* @param rai
* @return
*/
static <T extends RealType<T> & NativeType<T>>
SharedMemoryArray buildNumpyLikeSHMA(String name, RandomAccessibleInterval<T> rai) {
if (PlatformDetection.isWindows()) return SharedMemoryArrayWin.buildNumpyFormat(name, rai);
Expand Down Expand Up @@ -141,19 +220,27 @@ static String createShmName() {

/**
*
* @return
* @return the unique name for the shared memory, specified as a string. When creating a new shared memory bloc.k instance
* {@link SharedMemoryArray} a name can be supploed, and if not it will be generated automatically.
* Two shared memory blocks existing at the same time cannot share the name.
* In Unix based systems, Shared memory segment names start with "/", for example "/shm_block"
* In Windows shared memory block names start either with "Global\\" or "Local\\". Example: "Local\\shm_block"
*/
public String getName();

/**
*
* @return
* @return the unique name for the shared memory, specified as a string and as
* the Python package multiprocessing.shared_memory returns it. For Unix based systems it removes the
* initial "/", for example: "/shm_block" -> "shm_block".
* In Windows shared memory block names start either with "Global\\" or "Local\\", this is also removed when
* providing a shared memory name to Python. Example: "Local\\shm_block" -> "shm_block"
*/
public String getNameForPython();

/**
*
* @return
* @return the pointer to the shared memory segment
*/
public Pointer getPointer();

Expand All @@ -165,20 +252,22 @@ static String createShmName() {

/**
*
* @return
* @return the data type of the array that was flattened and copied into the shared memory segment
*/
public String getOriginalDataType();

/**
*
* @return
* @return the shape (array dimensions) of the array that was flattened and copied into the shared memory segment
*/
public long[] getOriginalShape();

/**
* Retrieve the {@link RandomAccessibleInterval} defined in the shared memory segment
*
* @param <T>
* @return
* possible ImgLib2 data types of the retrieved {@link RandomAccessibleInterval}
* @return the randomAccessible interval that is defined in the shared memory segment
*/
public <T extends RealType<T> & NativeType<T>> RandomAccessibleInterval<T> getSharedRAI();

Expand Down

0 comments on commit 50689b3

Please sign in to comment.