org.apache.activemq.artemis.jlibaio

Class LibaioContext<Callback extends SubmitInfo>

java.lang.Object

org.apache.activemq.artemis.jlibaio.LibaioContext<Callback>

All Implemented Interfaces:

Closeable, AutoCloseable

public class LibaioContext<Callback extends SubmitInfo>
extends Object
implements Closeable

This class is used as an aggregator for the LibaioFile.
It holds native data, and it will share a libaio queue that can be used by multiple files.
You need to use the poll methods to read the result of write and read submissions.
You also need to use the special buffer created by LibaioFile as you need special alignments when dealing with O_DIRECT files.
A Single controller can server multiple files. There's no need to create one controller per file.
Interesting reading for this.

Constructor Summary

Constructors

Constructor and Description
LibaioContext(int queueSize, boolean useSemaphore, boolean useFdatasync) The queue size here will use resources defined on the kernel parameter fs.aio-max-nr .

Method Summary

Modifier and Type	Method and Description
void	close() This is used to close the libaio queues and cleanup the native data used.
static void	close(int fd)
protected void	finalize()
static void	freeBuffer(ByteBuffer buffer) This will call posix free to release the inner buffer allocated at newAlignedBuffer(int, int).
static int	getBlockSize(File path)
static int	getBlockSize(String path)
static long	getTotalMaxIO() This is used to validate leaks on tests.
static boolean	isLoaded()
static boolean	lock(int fd)
void	memsetBuffer(ByteBuffer buffer) It will reset all the positions on the buffer to 0, using memset.
static void	memsetBuffer(ByteBuffer buffer, int size)
static ByteBuffer	newAlignedBuffer(int size, int alignment) Buffers for O_DIRECT need to use posix_memalign.
static int	open(String path, boolean direct) it will return a file descriptor.
static LibaioFile	openControlFile(String file, boolean direct) It will open a file disassociated with any sort of factory.
LibaioFile<Callback>	openFile(File file, boolean direct) It will open a file.
LibaioFile<Callback>	openFile(String file, boolean direct) It will open a file.
void	poll() It will start polling and will keep doing until the context is closed.
int	poll(Callback[] callbacks, int min, int max) It will poll the libaio queue for results.
static void	resetMaxAIO() This is used on tests validating for leaks.
void	submitRead(int fd, long position, int size, ByteBuffer bufferWrite, Callback callback)
void	submitWrite(int fd, long position, int size, ByteBuffer bufferWrite, Callback callback) Documented at LibaioFile.write(long, int, java.nio.ByteBuffer, SubmitInfo)

Methods inherited from class java.lang.Object

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

Constructor Detail

LibaioContext

public LibaioContext(int queueSize,
                     boolean useSemaphore,
                     boolean useFdatasync)

The queue size here will use resources defined on the kernel parameter fs.aio-max-nr .

Parameters:

queueSize - the size to be initialize on libaio io_queue_init which can't be higher than /proc/sys/fs/aio-max-nr.

useSemaphore - should block on a semaphore avoiding using more submits than what's available.

useFdatasync - should use fdatasync before calling callbacks.

Method Detail

isLoaded

public static boolean isLoaded()

getTotalMaxIO

public static long getTotalMaxIO()

This is used to validate leaks on tests.

Returns:

the number of allocated aio, to be used on test checks.

memsetBuffer

public void memsetBuffer(ByteBuffer buffer)

It will reset all the positions on the buffer to 0, using memset.

Parameters:

buffer - a native buffer. s

resetMaxAIO

public static void resetMaxAIO()

This is used on tests validating for leaks.

submitWrite

public void submitWrite(int fd,
                        long position,
                        int size,
                        ByteBuffer bufferWrite,
                        Callback callback)
                 throws IOException

Documented at LibaioFile.write(long, int, java.nio.ByteBuffer, SubmitInfo)

Parameters:

fd - the file descriptor

position - the write position

size - number of bytes to use

bufferWrite - the native buffer

callback - a callback

Throws:

IOException - in case of error

submitRead

public void submitRead(int fd,
                       long position,
                       int size,
                       ByteBuffer bufferWrite,
                       Callback callback)
                throws IOException

Throws:

IOException

close

public void close()

This is used to close the libaio queues and cleanup the native data used.
It is unsafe to close the controller while you have pending writes or files open as this could cause core dumps or VM crashes.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

openFile

public LibaioFile<Callback> openFile(File file,
                                     boolean direct)
                              throws IOException

It will open a file. If you set the direct flag = false then you won't need to use the special buffer. Notice: This will create an empty file if the file doesn't already exist.

Parameters:

file - the file to be open.

direct - will set ODIRECT.

Returns:

It will return a LibaioFile instance.

Throws:

IOException - in case of error.

openFile

public LibaioFile<Callback> openFile(String file,
                                     boolean direct)
                              throws IOException

It will open a file. If you set the direct flag = false then you won't need to use the special buffer. Notice: This will create an empty file if the file doesn't already exist.

Parameters:

file - the file to be open.

direct - should use O_DIRECT when opening the file.

Returns:

a new open file.

Throws:

IOException - in case of error.

openControlFile

public static LibaioFile openControlFile(String file,
                                         boolean direct)
                                  throws IOException

It will open a file disassociated with any sort of factory. This is useful when you won't use reading / writing through libaio like locking files.

Parameters:

file - a file name

direct - will use O_DIRECT

Returns:

a new file

Throws:

IOException - in case of error.

poll

public int poll(Callback[] callbacks,
                int min,
                int max)

It will poll the libaio queue for results. It should block until min is reached Results are placed on the callback.
This shouldn't be called concurrently. You should provide your own synchronization if you need more than one Thread polling for any reason.
Notice that the native layer will invoke SubmitInfo.onError(int, String) in case of failures, but it won't call done method for you.

Parameters:

callbacks - area to receive the callbacks passed on submission.The size of this callback has to be greater than the parameter max.

min - the minimum number of elements to receive. It will block until this is achieved.

max - The maximum number of elements to receive.

Returns:

Number of callbacks returned.

See Also:

LibaioFile.write(long, int, java.nio.ByteBuffer, SubmitInfo), LibaioFile.read(long, int, java.nio.ByteBuffer, SubmitInfo)

poll

public void poll()

It will start polling and will keep doing until the context is closed. This will call callbacks on SubmitInfo.onError(int, String) and SubmitInfo.done(). In case of error, both SubmitInfo.onError(int, String) and SubmitInfo.done() are called.

open

public static int open(String path,
                       boolean direct)

it will return a file descriptor.

Parameters:

path - the file name.

direct - translates as O_DIRECT On open

Returns:

a fd from open C call.

close

public static void close(int fd)

newAlignedBuffer

public static ByteBuffer newAlignedBuffer(int size,
                                          int alignment)

Buffers for O_DIRECT need to use posix_memalign.
Documented at LibaioFile.newBuffer(int).

Parameters:

size - needs to be % alignment

alignment - the alignment used at the dispositive

Returns:

a new native buffer used with posix_memalign

freeBuffer

public static void freeBuffer(ByteBuffer buffer)

This will call posix free to release the inner buffer allocated at newAlignedBuffer(int, int).

Parameters:

buffer - a native buffer allocated with newAlignedBuffer(int, int).

lock

public static boolean lock(int fd)

memsetBuffer

public static void memsetBuffer(ByteBuffer buffer,
                                int size)

getBlockSize

public static int getBlockSize(File path)

getBlockSize

public static int getBlockSize(String path)