uk.ac.starlink.array
Class CopyNDArray
java.lang.Object
uk.ac.starlink.array.DefaultArrayDescription
uk.ac.starlink.array.BridgeNDArray
uk.ac.starlink.array.ScratchNDArray
uk.ac.starlink.array.CopyNDArray
- All Implemented Interfaces:
- ArrayDescription, NDArray
public class CopyNDArray
- extends ScratchNDArray
Provides a copy of an existing NDArray with its data backed by a fast
random-access scratch array in memory or on local disk.
This may be used for instance to provide fast
access to an NDArray whose pixel values may be passing through
computationally intensive 'wrapper' layers, or to provide random
access to data supplied from a non-random stream.
The data and characteristics of the returned copy, including URL,
will be identical to that of the base array,
except that it will have random access, read access and write
access, and it is likely to have mapped access
(though cannot do so in the case in which the requested
dimensions imply more than Integer.MAX_VALUE pixels).
Note that the guaranteed readability and writability of the
returned object does not indicate that reading from or writing to
it will be affected by/have effects on the data of the
base array.
In construction an AccessMode parameter is used, which controls when data
gets copied.
If and only if the mode parameter represents read access
(READ or UPDATE) then all the data will be copied from the base
array to the scratch copy at construction time.
If and only if it represents write access (WRITE or UPDATE)
then all the data will be copied from the scratch copy to the
base array when the CopyNDArray is closed. The CopyNDArray
will close the base array when it is closed itself.
- Author:
- Mark Taylor (Starlink)
Fields inherited from class uk.ac.starlink.array.DefaultArrayDescription |
arrayDims, arrayHandler, arrayIsRandom, arrayIsReadable, arrayIsWritable, arrayNdim, arrayNpix, arrayOrder, arrayOrigin, arrayShape, arrayType |
Method Summary |
void |
close()
Declares that this NDArray will not be required for further use;
in particular that no further invocations will be made of the
getAccess method. |
URL |
getURL()
Returns the URL of this NDArray, or null if it does not have one. |
CopyNDArray
public CopyNDArray(NDArray nda,
AccessMode mode)
throws IOException
- Constructs a new NDArray containing the same data as a given one,
- Parameters:
nda
- the base NDArraymode
- the access mode with which the data needs to be
accessed; this controls the copying of data.
If null, read/writability is taken from the
isReadable/isWritable flags of nda
- Throws:
IOException
- if an I/O error occurs during the copy of
data from the base NDArray
getURL
public URL getURL()
- Description copied from interface:
NDArray
- Returns the URL of this NDArray, or null if it does not have one.
An NDArray will normally only have a URL if it has been created
using one of the calls to NDArrayFactory which takes a URL argument.
Feeding the returned URL to the NDArrayFactory will obtain the
same NDArray as this one.
Scratch NDArrays, and virtual NDArrays created by wrapping another
to give access using different characteristics (type, shape etc)
will in general not have a URL.
The return value must not change over the lifetime of this object.
- Specified by:
getURL
in interface NDArray
- Overrides:
getURL
in class BridgeNDArray
- Returns:
- the URL at which this NDArray resides, or null if it is
not persistent
close
public void close()
throws IOException
- Description copied from interface:
NDArray
- Declares that this NDArray will not be required for further use;
in particular that no further invocations will be made of the
getAccess method.
This method should be invoked on an NDArray
when it is no longer required for pixel access.
This allows reclamation of non-memory resources, and in the case
of writable arrays it may also be required to ensure that data
is flushed from buffers back to the actual pixel array.
An array should not however be closed if some other object might
still require pixel access to it via a retained reference.
The general rule is that an application
which obtains a new NDArray from a URL should arrange for
close to be called
on it at the end of its lifetime, but that utility routines which
perform operations on an NDArray should not close it after use
(though they should close any ArrayAccess objects
which they take out).
Note that closing an NDArray will normally result in closing any
arrays which it wraps.
Multiple calls of this method may harmlessly be made.
- Specified by:
close
in interface NDArray
- Overrides:
close
in class BridgeNDArray
- Throws:
IOException
- if some I/O error occurred
Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.