Brion  1.6.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

BRION_API SpikeReport (const URI &uri, const int mode)
 Create a SpikeReport object given a URI. More...
 
BRION_API ~SpikeReport ()
 Destructor. More...
 
BRION_API const URI & getURI () const
 Get the URI used to instantiate the report. More...
 
BRION_API ReadMode getReadMode () const
 
BRION_API float getStartTime () const
 Get the time of the first spike. More...
 
BRION_API float getEndTime () const
 Get the time of the last spike. More...
 
BRION_API const SpikesgetSpikes () const
 Get the spike times and cell GIDs. More...
 
BRION_API void writeSpikes (const Spikes &spikes)
 Writes the spike times and cell GIDs. More...
 
BRION_API 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...
 
BRION_API float getNextSpikeTime ()
 Return the time of the next spike available in the internal cache. More...
 
BRION_API float getLatestSpikeTime ()
 Return the time of the latest spike that has been received. More...
 
BRION_API void clear (const float startTime, const float endTime)
 Remove all spikes contained in the given time interval. More...
 
BRION_API 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 66 of file spikeReport.h.

Member Enumeration Documentation

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

Version
1.4

Definition at line 73 of file spikeReport.h.

Constructor & Destructor Documentation

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

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. Support for additional types can be added through plugins; see SpikeReportPlugin for the details.
modethe brion::AccessMode bitmask
Exceptions
std::runtime_errorif the input URI is not handled by any registered spike report plugin.
Version
1.4
BRION_API brion::SpikeReport::~SpikeReport ( )

Destructor.

Version
1.3

Member Function Documentation

BRION_API 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
BRION_API 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
BRION_API 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
BRION_API float brion::SpikeReport::getLatestSpikeTime ( )

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

Returns
undefined in STATIC reports. Let t be the timestamp of the latest spike received, in STREAM reports it returns:
  • UNDEFINED_TIMESTAMP is no spike has been received
  • t if at least one spike has been received and the end of the stream has not been reahed.
  • An unspecified value x, such as x > t, if at least one spike has been received and the end of the stream has been reached.

In any case, the function waitUntil() is guaranteed to not block if it 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
BRION_API 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
BRION_API ReadMode brion::SpikeReport::getReadMode ( ) const
Version
1.4
BRION_API 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
BRION_API 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
BRION_API 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
1.6
BRION_API 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
BRION_API 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: