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

Read access to a SpikeReport. More...

#include <spikeReport.h>

+ Inheritance diagram for brion::SpikeReport:
+ Collaboration diagram for brion::SpikeReport:

Public Types

enum  ReadMode { STATIC = 0, STREAM }
 A type to specify how spikes are read by this SpikeReport. More...
 

Public Member Functions

 SpikeReport (const URI &uri, const int mode)
 Create a SpikeReport object given a URI. More...
 
 ~SpikeReport ()
 Destructor. More...
 
ReadMode getReadMode () const
 
float getStartTime () const
 Get the time of the first spike. More...
 
float getEndTime () const
 Get the time of the last spike. More...
 
const Spikes & getSpikes () const
 Get the spike times and cell GIDs. More...
 
void writeSpikes (const Spikes &spikes)
 Writes the spike times and cell GIDs. More...
 
bool waitUntil (const float timeStamp, const uint32_t timeout=LB_TIMEOUT_INDEFINITE)
 Lock the caller until the first spike past the given time stamp arrives or the network stream is closed by the source. More...
 
float getNextSpikeTime ()
 Return the time of the next spike available in the internal cache. More...
 
float getLatestSpikeTime ()
 Return the time of the latest spike that has been received. More...
 
void clear (const float startTime, const float endTime)
 Remove all spikes contained in the given time interval. More...
 
void close ()
 Closes the report. More...
 

Detailed Description

Read access to a SpikeReport.

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 waitUntil. The user can clear spikes stored inside a given time window. In this report type, getStartTime and getEndTime return the time window of the spikes that are available to the client.

    Client code can implement a moving window using waitUntil() and getNextSpikeTime(). The conceived usage is to decide a window width, and call waitUntil() using getNextSpikeTime() + width.

    The loop

    while( report.waitUntil( report.getNextSpikeTime( )))
    ;

    is guaranteed to always make progress until the end of the stream is reached.

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

Definition at line 65 of file spikeReport.h.

Member Enumeration Documentation

A type to specify how spikes are read by this SpikeReport.

Version
1.4

Definition at line 72 of file spikeReport.h.

Constructor & Destructor Documentation

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

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.
modethe brion::AccessMode bitmask
Exceptions
std::runtime_errorif the input URI is not handled by any registered spike report plugin.
Version
1.4
brion::SpikeReport::~SpikeReport ( )

Destructor.

Version
1.3

Member Function Documentation

void brion::SpikeReport::clear ( const float  startTime,
const float  endTime 
)

Remove all spikes contained in the given time interval.

The purpose of this method is to implement a moving window on top of this API.

Parameters
startTimeThe start point of the interval
endTimeThe end point, if smaller than startTime no operation is performed
Exceptions
std::runtime_erroris the operation is not supported by the reader.
Version
1.4
void brion::SpikeReport::close ( )

Closes the report.

Only meaningful for STREAM based reports. For reports opened in write mode it finishes the reporting. For reports opened in read mode it disconnects from the source, any call waiting in waitUntil will be unblocked.

Implicitly called by the destructor. Calling any other function after the report has been closed has undefined behavior.

Version
1.4
float brion::SpikeReport::getEndTime ( ) const

Get the time of the last spike.

Returns
The time in milliseconds, or UNDEFINED_TIMESTAMP if there are no spikes.
Version
1.3
float brion::SpikeReport::getLatestSpikeTime ( )

Return the time of the latest spike that has been received.

Returns
undefined in STATIC reports. In STREAM reports it reports the latest timestamp that has been received or UNDEFINED_TIMESTAMP if no spikes have been received. The function waitUntil() is guaranteed to not block if takes as input a valid timestamp smaller than the value returned by getLatestSpikeTime().
Exceptions
std::runtime_errorif invoked on non STREAM writers.
Version
1.4
float brion::SpikeReport::getNextSpikeTime ( )

Return the time of the next spike available in the internal cache.

Returns
undefined in STATIC reports. In STREAM reports there are several cases:
  • 0 if no spikes have been received.
  • The earliest spike time in milliseconds than has been received, but has not been digested by waitUntil() if the internal cache is not empty.
  • The latest timestamp that was extracted from the cache if the cache is empty.
  • UNDEFINED_TIMESTAMP if the end of the stream has been reached and the cache is empty.
Exceptions
std::runtime_errorif invoked on non STREAM writers.
Version
1.4
ReadMode brion::SpikeReport::getReadMode ( ) const
Version
1.4
const Spikes& brion::SpikeReport::getSpikes ( ) const

Get the spike times and cell GIDs.

In STREAM reports this method returns all the spikes than have been moved from the receive cache.

Version
1.3
float brion::SpikeReport::getStartTime ( ) const

Get the time of the first spike.

Returns
The time in milliseconds, or UNDEFINED_TIMESTAMP if there are no spikes.
Version
1.3
bool brion::SpikeReport::waitUntil ( const float  timeStamp,
const uint32_t  timeout = LB_TIMEOUT_INDEFINITE 
)

Lock the caller until the first spike past the given time stamp arrives or the network stream is closed by the source.

This is the only function that updates the Spikes data set returned by getSpikes() with the spikes received from the stream.

Parameters
timeStampThe spike time to wait for in milliseconds. Using UNDEFINED_TIMESTAMP will make this function wait until the end of the stream.
timeoutAn optional timeout in milliseconds.
Returns
true at the moment a spike with time stamp larger than the input parameter arrives. False if any of the events below occur before the desired timestamp arrives:
  • The timeout goes off.
  • The network stream is closed or reaches the end.
  • The report is closed.
Exceptions
std::runtime_errorif invoked on STATIC readers.
Version
1.4
void brion::SpikeReport::writeSpikes ( const Spikes &  spikes)

Writes the spike times and cell GIDs.

Parameters
spikesSpikes to write.
Exceptions
std::runtime_errorif invoked on spike readers.
Version
1.4

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