|
MasterScan
Lab_Matlab_control Master Branch
|
Utility to organize incremental reading and writing of data.
topsDataFile facilitates writing data to a single file, incrementally, over time. It keeps track of data increments themeselves as well as metadata related to which increments have already been written. It also facilitates reading incremental data and keeps track of which increments have already been read out.
topsDataFile is suitable for sharing data (such as topsDataLog data) between separate instance of Matlab running on the same machine. Each Matlab instance should be able to write data increments and read in increments that were written by the other. topsDataFile attempts to prevent data corruption due to poorly timed access by saving data and metadata separately, and using metadata to coordinate file access.
Note that topsDataFile objects are not handle objects, and topsDataFile objects themselves are not returned directly. Instead, the newHeader() methods returns a struct with fields that match the properties of the topsDataFile class, and other topsDataFile methods expect to work with these "header" structs. This pattern faciliitates writing and reading of header meta data to file. It also makes explicit the idea that topsDataFile objects represent data on the hard disk, and should not themselves contain much data or maintain much internal state.
Properties and Events | |
| Property | fileWithPath = 'topsDataFileData.mat' |
| string name of the file to read from and write to, which may include the file path | |
| Property | incrementPrefix = 'topsDataFileIncrement' |
| string prefix to use for identifying data increments | |
| Property | dateTimeFunction = @now |
| function handle for getting the current date-and-time as a number | |
| Property | datestrFormat = 'yyyymmddTHHMMSSPFFF' |
| format string to use with Matlab's builtin datestr() | |
| Property | writtenIncrements = [] |
| array of date-and-time numbers for previously written data increments | |
| Property | readIncrements = [] |
| array of date-and-time numbers for previously read data increments | |
| Property | userData = [] |
| any external data to be stored with the header metadata | |
Static Methods | |
| static fHeader | newHeader (varargin) |
| Create a header struct with fields that match the properties of the topsDataFile class. More... | |
| static fHeader incrementCell | read (fHeader, increments) |
| Read any new data increments from a topsDataFile. More... | |
| static fHeader | write (fHeader, newIncrement) |
| Write a new data increment to a topsDataFile. More... | |
| static names | incrementNamesFromNumbers (fHeader, numbers) |
| Get data increment names from date-and-time numbers. | |
Private Methods | |
| fHeader | toStruct (fObj) |
| Convert a topsDataFile object to an equivalent struct. | |
|
static |
Create a header struct with fields that match the properties of the topsDataFile class.
| varargin | optional property-value pairs to assign to the new header. |
Use this method instead of the topsDataFile constructor.
Returns a header struct with fields and default values that match those of the topsDataFile class. varargin may contain pairs of property names and values to be assigned to the new struct.
|
static |
Read any new data increments from a topsDataFile.
| fHeader | a topsDataFile header struct as returned from newHeader(). |
| increments | optional array of date-and-time numbers identifying data increments to read or re-read from the topsDataFile |
Uses fHeader to locate a topsDataFile on disk. If the file exists and contains topsDataFile header metadata, loads the metadata from disk and updates fHeader to match. Returns the updated fHeader
Also returns a cell array containing any data increments that have not yet been read from disk. These increments correspond to values in fHeader.writtenIncrements that are not yet present in fHeader.readIncrements.
If increments is provided, attempts to read or re-read the specified data increments from the topsDataFile. Returns a cell array with the same size as increments. Where the specified increments are not present in the topsDataFile, the returned cell array will be empty. Using read() in this way will not affect fHeader.readIncrements, or subsequent calls to read().
|
static |
Write a new data increment to a topsDataFile.
| fHeader | a topsDataFile header struct as returned from newHeader(). |
| newIncrement | any data increment to append to the topsDataFile |
If newIncrement is provided, appends the newIncrement to the topsDataFile on disk, then updates the hjeader metadata on disk. If a@ newIncrement is omitted, only writes header metadata to disk. If the topsDataFile doesn't already exist on disk, creates the new file first.
Since write() updates header metadata only after writing the new increment data, concurrent read() calls, such as from a separate Matlab instance, should be able to safely ignore increment data that's in the process of being written.
Returns fHeader, which may have been modified with new metadata.
1.8.15