B
- the I/O buffer type.public interface BufferAccess<B extends java.nio.Buffer>
BufferAccess
interface provides methods for getting access to the
device (or the driver thereof) I/O buffers, if any. A device driver may through
this interface provide access to direct buffers that are suitable for efficient
direct I/O operations such as using Direct Memory Access (DMA). This interface
additionally provides a method that wraps an application-provided direct buffer
into a buffer suitable for efficient direct I/O operations.
The following sample code illustrates how the internal device's buffer might be used to perform efficient I/O operations (assuming the feature is supported):
// Iterativelly creates a series of samples according to some requirement... private boolean createSamples(IntBuffer buffer) { ... } // Generates the sampled output signal; this code is more efficient if all the // samples to generate fit within the device's output buffer. try (DACChannel dac = DeviceManager.open(channelID)) { IntBuffer buffer = dac.getOutputBuffer(); while (createSamples(buffer)) { // Directly creates the samples in the driver's internal buffer dac.generate(buffer); buffer.clear(); } } catch (IOException ex) { // ... }
The following sample code illustrates how an application may use a (pre-allocated) direct buffer to to perform efficient I/O operations (assuming the feature is supported):
ByteBuffer someBuffer = ... // Some already allocated buffer try (DACChannel dac = DeviceManager.open(channelID)) { someBuffer.clear(); // Clear the buffer to make sure its full capacity can be used IntBuffer buffer = dac.prepareBuffer(someBuffer, 128); if (buffer == null) { // The provided buffer is not direct and/or is not suitable for efficient transfer buffer = someBuffer.asIntBuffer(); // The device will default to less efficient transfer mode } while (createSamples(buffer)) { dac.generate(buffer); buffer.clear(); } } catch (IOException ex) { // ... } }
Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the device I/O buffers until any on-going operation has completed. Interfering with an on-going I/O operation by accessing and modifying a device I/O buffer concurrently may yield unpredictable results.
Modifier and Type | Method and Description |
---|---|
B |
getInputBuffer()
Gets the direct input buffer of this device (optional
operation).
|
B |
getOutputBuffer()
Gets the direct output buffer of this device (optional
operation).
|
B |
prepareBuffer(java.nio.ByteBuffer buffer,
int size)
Creates a view of the provided
ByteBuffer suitable for efficient
direct I/O transfers of the specified size and of the type required by this
device. |
B getInputBuffer() throws ClosedDeviceException, java.io.IOException
The input buffer will get allocated on a per-application basis to avoid conflicts; but only one such buffer will be allocated per application. The capacity of the buffer will be determined based on the property of the underlying device.
When the returned Buffer
instance is invalidated because the device
is either closed or in exclusive use by some other application then an
attempt to access the Buffer
instance will not change the buffer's
content and will cause a ClosedDeviceException
or some other
unspecified exception to be thrown either at the time of the access or at
some later time.
java.lang.UnsupportedOperationException
- if this device (or driver thereof)
does not have or does not allow direct access to its input buffer.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if an I/O error occurred such as the device is not
readable.B getOutputBuffer() throws ClosedDeviceException, java.io.IOException
The output buffer will get allocated on a per-application basis to avoid conflicts; but only one such buffer will be allocated per application. The capacity of the buffer will be determined based on the property of the underlying device.
When the returned Buffer
instance is invalidated because the device
is either closed or in exclusive use by some other application then an
attempt to access the Buffer
instance will not change the buffer's
content and will cause a ClosedDeviceException
or some other
unspecified exception to be thrown either at the time of the access or at
some later time.
java.lang.UnsupportedOperationException
- if this device (or driver thereof)
does not have or does not allow direct access to its output buffer.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if an I/O error occurred such as the device is not
writable.B prepareBuffer(java.nio.ByteBuffer buffer, int size) throws java.io.IOException, ClosedDeviceException
ByteBuffer
suitable for efficient
direct I/O transfers of the specified size and of the type required by this
device. If the provided buffer is a direct buffer then the alignment of its current
position, and its limit are checked; if eligible for direct I/O operation, a
new buffer - of the required type - whose content is a shared subsequence of the provided
buffer's content is created as follows:
If the provided buffer is not direct or is not eligible for direct I/O (or
if direct I/O is not supported) then null
is returned. The
provided buffer may still be used for the intended I/O operation but in
this case, the device's driver may resort to less efficient procedures
to perform the I/O operation.
buffer
- the buffer to prepare for efficient I/O transfer.size
- the size of the intended data to transfer.null
otherwise.java.lang.IllegalArgumentException
- if size
is negative.ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.Copyright © 2012, 2015, Oracle and/or its affiliates. All rights reserved.
Legal Notices