Brion  2.0.0
The Blue Brain C++ I/O library
brion::SpikeReport Class Reference

Read/writes access to a spike report. More...

#include <spikeReport.h>

+ Collaboration diagram for brion::SpikeReport:

Public Types

enum  State { ok, ended, failed }
 The State enum : describe the state of the report State::ok means that the report is ready to be read/written State::ended means that the report end is reached (in read mode) State::failed means that a error occured when readyn or writing the report.
 

Public Member Functions

 SpikeReport (const URI &uri, int mode=MODE_READ)
 Create a SpikeReport object given a URI. More...
 
 SpikeReport (const URI &uri, const GIDSet &ids)
 Open a report in read mode with a subset selection. More...
 
 ~SpikeReport ()
 Release all resources. More...
 
 SpikeReport (SpikeReport &&)
 
SpikeReportoperator= (SpikeReport &&)
 
void close ()
 Close the report. More...
 
bool isClosed () const
 
void interrupt ()
 Interrupt any pending read/seek operation. More...
 
const URI & getURI () const
 Get the URI used to instantiate the report. More...
 
float getCurrentTime () const
 
float getEndTime () const
 
State getState () const
 
std::future< Spikes > read (float min)
 Read spikes until getCurrentTime becomes > min, the end of the report is reached or the report closed. More...
 
std::future< Spikes > readUntil (float max)
 Read spikes until getCurrentTime() >= max, the end of the report is reached or the report closed. More...
 
std::future< void > seek (float toTimeStamp)
 Seek to a given absolute timestamp. More...
 
void write (const Spikes &spikes)
 Write the given spikes to the output. More...
 
bool supportsBackwardSeek () const
 

Static Public Member Functions

static std::string getDescriptions ()
 

Detailed Description

Read/writes access to a spike report.

Following RAII, this class is ready to use after the creation and will ensure release of resources upon destruction.

There are two type of SpikeReports, depending on the semantics of the data source:

  • Static reports: The full spike data base is made available at construction time. This is the mode used by Bluron and NEST report file readers.
  • Stream based reports: Spikes are read from a network stream. The stream always moves forward in time. The reader cannot steer or control how the source produces the spikes. Spikes are cached internally and made available by calling read/readUntil

This class is not thread-safe except where stated otherwise.

Definition at line 56 of file spikeReport.h.

Constructor & Destructor Documentation

brion::SpikeReport::SpikeReport ( const URI &  uri,
int  mode = MODE_READ 
)

Create a SpikeReport object given a URI.

Parameters
uriURI to spike report. The report type is deduced from here. The report types with built-in support are:
  • Bluron ('dat' extension), Bluron file based reports.
  • NEST ('gdf' extension). NEST file based reports. In read mode, shell wildcards are accepted at the file path leaf to load multiple report files.
  • Binary ('spikes' extension) Support for additional types can be added through plugins; see SpikeReportPlugin for the details.
modethe brion::AccessMode bitmask. The report can be open only in brion::MODE_READ or brion::MODE_WRITE modes.
Exceptions
std::runtime_errorif the input URI is not handled by any registered spike report plugin.
Version
2.0
brion::SpikeReport::SpikeReport ( const URI &  uri,
const GIDSet ids 
)

Open a report in read mode with a subset selection.

Parameters
urithre port uri
subsetThe set of gids to be reported. This set should be understood as a filter: any included GID which is not actually part of the report will be silently ignored when reading data.
Version
2.0
brion::SpikeReport::~SpikeReport ( )

Release all resources.

Any pending read/seek tasks will be interrupted and calling get on the corresponding future will throw std::runtime_error.

Member Function Documentation

void brion::SpikeReport::close ( )

Close the report.

The close operation is blocking and it interrupts all the pending read/seek operations.

Version
2.0
float brion::SpikeReport::getCurrentTime ( ) const
Returns
the end time of the latest complete read/write operation or 0 if no operation has been issued.

Read operations are deemed as complete when the returned future is ready.

The time inverval to which getCurrentTime refers is open on the right. That means that upon completion of a read or write operation no spike read or written may have a timestamp >= getCurrentTime().

Version
2.0
static std::string brion::SpikeReport::getDescriptions ( )
static
Returns
the descriptions of all loaded report backends.
Version
1.10
float brion::SpikeReport::getEndTime ( ) const
Returns
the end timestamp of the report. This is the timestamp of the last spike known to be available or written or larger if the implementation has more metadata available. For stream reports this time is 0 before any operation is completed.
Version
2.0
State brion::SpikeReport::getState ( ) const
Returns
The state after the last completed operation.
Version
2.0
const URI& brion::SpikeReport::getURI ( ) const

Get the URI used to instantiate the report.

It could be different from the input URI, depending on the plugin implementation.

Returns
The URI used in the instance. It could be the same as the input URI or a different one, depending on the implementation
Version
2.0
void brion::SpikeReport::interrupt ( )

Interrupt any pending read/seek operation.

This method is blocking.

Version
2.0
bool brion::SpikeReport::isClosed ( ) const
Returns
true if the report was closed
Version
2.0
std::future<Spikes> brion::SpikeReport::read ( float  min)

Read spikes until getCurrentTime becomes > min, the end of the report is reached or the report closed.

This function fetches all the available data from the source. If no error occurs and the end is not reached, the min value passed is also guaranteed to be inside the time window of the data returned.

Preconditions:

  • r.getState() is State::ok
  • The report was open in read mode.
  • There is no previous read or seek operation with a pending future.

Postconditions: Let:

  • r be the SpikeReport
  • f be the returned future by r.read(min)
  • and s = r.getCurrentTime() before read is called: After f.wait() returns the following are all true:
  • r.getCurrentTime() >= s
  • If r.getState() == State::ok, then r.getCurrentTime() > min
  • For each spike timestamp t_s in f.get(), s <= t_s < r.getCurrentTime() (Note this could collapse to an empty interval if r.getState() != State::ok)

After successful f.wait_for or f.wait_until, the result is the same as above. If they time out, no observable state changes.

If the state is FAILED or some other operation is still pending when read is called the result is undefined.

Parameters
minThe minimum end time until which spikes will be read. If UNDEFINED_TIMESTAMP, it will be considered as -infinite. This means that as much data as possible will be fetched without a minimum.
Exceptions
std::logic_errorif one of the preconditions is not fulfilled.
Note
Until the completion of this operation, the internal state of the SpikeReport may change.
Version
2.0
std::future<Spikes> brion::SpikeReport::readUntil ( float  max)

Read spikes until getCurrentTime() >= max, the end of the report is reached or the report closed.

This function is very similar to the normal read, but instead of specifying a lower bound of getCurrentTime at return, it specifies a requested strict value. The preconditions and postconditions are the same except for those involving the parameter min which become:

Precondition: max > getCurrentTime() Postcondition: If r.getState() == State::ok, then r.getCurrentTime() >= max

Exceptions
std::runtime_errorif the precondition does not hold.
Note
Until the completion of this operation, the internal state of the SpikeReport may change.
See also
seek()
Version
2.0
std::future<void> brion::SpikeReport::seek ( float  toTimeStamp)

Seek to a given absolute timestamp.

If toTimestamp >= getCurrentTime() and the report was open for reading, data will be skipped forward until the timestamp is made current. In write mode for streams, consumers are notified about the new timestamp.

The case toTimestamp < getCurrentTime() is only supported by file based reports. In write mode, seeks are only supported in binary reports. Forward seeking simply updates getCurrentTime() and backward seeking followed by a write, will overwrite the existing data.

If the seek operation is not supported, a std::runtime_error will be thrown if this method is called.

Preconditions:

  • There is no standing read or readUntil operation.

Postconditions: Let:

  • r be the SpikeReport
  • f be the returned future by r.seek(toTimestamp) Then:
  • After f.wait() returns r.getCurrentTime() == toTimestamp.
  • The postconditions of read operations imply that in forward skips this function throws away the data previous to toTimestamp (or avoids reading it at all if possible).
Exceptions
std::runtime_errorif a precondition does not hold or the operation is not supported by the implementation.
Note
Until the completion of this operation, the internal state of the SpikeReport may change.
Version
2.0
bool brion::SpikeReport::supportsBackwardSeek ( ) const
Returns
Whether the report supports seek to t < getCurrentTime() or not.
Version
2.0
void brion::SpikeReport::write ( const Spikes &  spikes)

Write the given spikes to the output.

Preconditions:

Upon return getCurrenTime() is the greatest of all the spike times plus an epsilon.

Parameters
spikesA collection of spikes sorted by timestamp in ascending order. For every spike, its timestamp must be >= getCurrentTime().
Exceptions
std::runtime_errorif the report is read-only,
std::logic_errorif a precondition does not hold
Version
2.0

The documentation for this class was generated from the following file: