A connection to the NDS/NDS2 server. More...

#include <nds.hh>

Classes
class	already_closed_error
	Signal that the connection has already been closed. More...

class	daq_error
	an error state was returned by the NDS server More...

class	error
	Base class for NDS errors. More...

class	minute_trend_error
	Signals that a minute trend has been requested but the start/stop times are not divisible by 60. More...

class	transfer_busy_error
	A transfer is already in progress. More...

class	unexpected_channels_received_error
	An unexpected channel or data was received. More...

Public Types
enum	protocol_type { PROTOCOL_INVALID = -1, PROTOCOL_ONE = 1, PROTOCOL_TWO = 2, PROTOCOL_TRY = 3 }
	Connection constants. More...

typedef std::string	host_type
	Host name type.

typedef int	port_type
	Host port number type.

typedef size_t	count_type
	Generic count time.

typedef channel::channel_names_type	channel_names_type
	A list of channel names.

Public Member Functions
DLL_EXPORT	connection ()=delete
	Default constructor.

DLL_EXPORT	connection (const host_type &host, port_type port=DEFAULT_PORT, protocol_type protocol=PROTOCOL_TRY)
	Create a connection. More...

DLL_EXPORT	connection (const NDS::parameters &params)
	Create a connection object, initialized with parameters from a parameters object. More...

	connection (const NDS::connection &other)=delete
	Connection objects are not copyable.

connection &	operator= (const NDS::connection &other)=delete
	Connection objects are not copyable.

DLL_EXPORT	~connection ()
	Destroy the connection.

DLL_EXPORT void	close ()
	Close the connection.

DLL_EXPORT count_type	count_channels (const channel_predicate_object &pred)
	Return the count of channels matching the given predicate. More...

DLL_EXPORT channels_type	find_channels (const channel_predicate_object &pred)
	Retrieve a list of channels. More...

DLL_EXPORT epochs_type	get_epochs ()
	Return a list of epochs. More...

DLL_EXPORT availability_list_type	get_availability (const epoch &time_span, const channel_names_type &channel_names)
	Given a list of channels return their availability over the current epoch. More...

DLL_EXPORT bool	check (buffer::gps_second_type gps_start, buffer::gps_second_type gps_stop, const channel_names_type &channel_names)
	Check to see if data is avaiable. More...

DLL_EXPORT buffers_type	fetch (buffer::gps_second_type gps_start, buffer::gps_second_type gps_stop, const channel_names_type &channel_names)
	Retreive data from the server. More...

DLL_EXPORT NDS::parameters &	parameters () const
	Return the parameter/configuration object. More...

DLL_EXPORT const channel::hash_type &	hash () const
	Return the NDS2 channel hash. More...

DLL_EXPORT NDS::data_iterable	iterate (NDS::request_period period, const channel_names_type &channel_names)
	Retreive data in segments. More...

DLL_EXPORT bool	request_in_progress () const
	Query the connection to see if a request is in progress. More...

Static Public Attributes
static const port_type	DEFAULT_PORT
	Default NDS2 port number.

Detailed Description

A connection to the NDS/NDS2 server.

The connection object is used to interact with the NDS (v1 or v2) servers to retrieve data and channel lists. Connnection objects have a few main categories of methods:

Data retreival (fetch and iterate)
Channel listing and counting (find_channels and count_channels)
Channel availability checking (get_availability)

Member Enumeration Documentation

enum NDS::abi_0::connection::protocol_type

Connection constants.

Enumerator
PROTOCOL_INVALID	Unknown or invalid connection.
PROTOCOL_ONE	Connect with NDS1 protocol.
PROTOCOL_TWO	Connect with NDS2 protocol.
PROTOCOL_TRY	Autodetect server protocol.

Constructor & Destructor Documentation

NDS::abi_0::connection::connection	(	const host_type &	host,
		port_type	port = `DEFAULT_PORT`,
		protocol_type	protocol = `PROTOCOL_TRY`
	)

explicit

Create a connection.

Parameters

[in]	host	Server to connect to
[in]	port	Port number to connect to (defaults to DEFAULT_PORT)
[in]	protocol	Protocol version to use (defaults to PROTOCOL_TRY)

NDS::abi_0::connection::connection ( const NDS::parameters & params )

explicit

Create a connection object, initialized with parameters from a parameters object.

Parameters

[in] params The parameter/configuration object used to specify the connection parameters and options.

Note: params is deep copied.

Member Function Documentation

bool NDS::abi_0::connection::check	(	buffer::gps_second_type	gps_start,
		buffer::gps_second_type	gps_stop,
		const channel_names_type &	channel_names
	)

Check to see if data is avaiable.

Given a start/stop time and a channel list check to see if a fetch request would suceed. This will return failure if there is a gap in the data, or if the data is on tape.

Parameters

[in]	gps_start	Start time of request
[in]	gps_stop	Stop time of request
[in]	channel_names	The channel list

Returns: True if the data is availble and not on tape

connection::count_type NDS::abi_0::connection::count_channels ( const channel_predicate_object & pred )

Return the count of channels matching the given predicate.

Return a count of channels that are available form this connection within the given contstraints.

Parameters

[in] pred A ChannelPredicate object holding the constraints to impose on the search.

Returns: A count of channels matching the input parameters.

Remarks: For NDS1 a local cache of the channel list is searched. For NDS2 this call may result in one or more requests to the server, no local cache is used.

// Return all channels

auto chan_count = conn.count_channels(channel_predicate());

// Return all DMT channels
auto chan_count =
conn.count_channels(channel_predicate("*DMT*"));

// Return all 16Hz-2KHz channels that are 32 bit integers
auto chan_count =
conn.count_channels(channel_predicate(FrequencyRange(16.0,
2000.), channel::data_type::DATA_TYPE_INT32);

// Return all 16Hz-2KHz channels that are 32 bit integers
// from O1
auto chan_count =
conn.count_channels(channel_predicate(FrequencyRange(16.0,
2000.), channel::data_type::DATA_TYPE_INT32,
epoch("O1"));

buffers_type NDS::abi_0::connection::fetch	(	buffer::gps_second_type	gps_start,
		buffer::gps_second_type	gps_stop,
		const channel_names_type &	channel_names
	)

Retreive data from the server.

Given a start/stop time and a channel list retrieve the associated data.

Parameters

[in]	gps_start	Start time of request
[in]	gps_stop	Stop time of request
[in]	channel_names	The channel list

Returns: A list of buffers containing the request data.

Remarks: This command can respond to missing data and high latency situations in various ways. Use the (get/set)_parameter function to set how data gaps or data on tape situations are handled.

channels_type NDS::abi_0::connection::find_channels ( const channel_predicate_object & pred )

Retrieve a list of channels.

Return a list of channels that are available form this connection within the given contstraints.

Parameters

[in] pred A ChannelPredicate object holding the constraints to impose on the search.

Returns: A count of channels matching the input parameters.

Remarks: For NDS1 a local cache of the channel list is searched. For NDS2 this call may result in one or more requests to the server, no local cache is used.

// Return all channels

auto chans = conn.find_channels(channel_predicate());

// Return all DMT channels

auto chans = conn.find_channels(channel_predicate("*DMT*"));

// Return all 16Hz-2KHz channels that are 32 bit integers
auto chans =
conn.find_channels(channel_predicate(FrequencyRange(16.0, 2000.),
channel::data_type::DATA_TYPE_INT32);

// Return all 16Hz-2KHz channels that are 32 bit integers
// from the O1 run.
auto chans =
conn.find_channels(channel_predicate(FrequencyRange(16.0, 2000.),
channel::data_type::DATA_TYPE_INT32, epoch("O1"));

availability_list_type NDS::abi_0::connection::get_availability	(	const epoch &	time_span,
		const channel_names_type &	channel_names
	)

Given a list of channels return their availability over the current epoch.

Parameters

[in]	time_span	A epoch limiting start/stop time of the availability check
[in]	channel_names	A list of channels to return availability for.

Returns: A list a channel availabilities. There is one set of aviailabilities returned per channel requested.

epochs_type NDS::abi_0::connection::get_epochs ( )

Return a list of epochs.

NDS2 has the concept of epochs. A epoch may be set on a connection to constrain all data and channel requests to a given time frame. This call returns the currently available epochs.

Returns: A list of epochs

Remarks: Only available on NDS2 connections.

const channel::hash_type & NDS::abi_0::connection::hash ( ) const

Return the NDS2 channel hash.

NDSv2 server can return a hash of its internal channel list. This hash value can be used by a client to determine if the channel list has updated.

Returns: A hash value.

Remarks: NDSv2 only.

DLL_EXPORT NDS::data_iterable NDS::abi_0::connection::iterate	(	NDS::request_period	period,
		const channel_names_type &	channel_names
	)

Retreive data in segments.

Setup an iterative data retrieval process. This function initiates the request for data in range specified by period, but does not actually retreive the data. Instead it returns a data_stream object which manages the data iteration request.

Parameters

[in]	period	The range of data to return. It may be any range that a request_period may express, including unbounded live data, bounded live data, or bounded historical data.
[in]	channel_names	The list of channels to retrieve data for.

Returns: A data_iterable object which manages the iteration.

Note: The iteration must be completed before any other operation can take place on the connection object.

// to stream live data from a connection object 'conn'.
auto stream = conn->iterate(NDS::request_period(),
{"H1:GDS-CALIB_STRAIN,online",});
for (auto it:stream) {
     // *it will be a std::shared_ptr<NDS::buffers_type>
     std::cout << (*it)->Start();
}

// To stream historical data, skipping over gaps
// it is assumed that start, stop are defined elsewhere
// but are in scope.
conn->parameters().set("ITERATE_USE_GAP_HANDLERS", "false");
auto stream = conn->iterate(NDS::request_period(start, stop),
{"H1:GDS-CALIB_STRAIN,online",});
for (auto it:stream) {
     // *it will be a std::shared_ptr<NDS::buffers_type>
     std::cout << (*it)->Start();
}

parameters & NDS::abi_0::connection::parameters ( ) const

Return the parameter/configuration object.

Returns: A const reference to the parameter/configuration object for the connection.

bool NDS::abi_0::connection::request_in_progress ( ) const

Query the connection to see if a request is in progress.

Returns: True if a request is in progress, else false.

Remarks: A connection can only do on request at a time.

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

src/libndscxx/module/nds_connection.hh
src/libndscxx/module/nds_connection.cc

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation