Common Type Definitions

Library of common type definitions.

#include <pvxs/nt.h>
namespace pvxs { namespace nt { ... } }

Contents:

Note

The nt::* factories are relatively expensive. Call them once, then use pvxs::Value::cloneEmpty() on the result.

Forward Compatibility

The Value objects returned by the NT* type builders are considered part of the API for the purposes of the Release Policy. Addition of a field is considered a compatible change. An incompatible change being:

  • Removal of a structure field

  • A field type change which restricts allowed assignments. eg. changing int32_t -> string would be compatible, but string -> int32_t would not.

The status of change to a struct ID string are currently undefined with respect to compatibility as the consequences have not yet been explored in practice.

time_t

Commonly used sub-structure to represent a time

struct TimeStamp

The time_t struct

// equivalent
struct time_t {
    int64_t secondsPastEpoch;
    int32_t nanoseconds;
    int32_t userTag;
};
Since

0.1.4

“secondsPastEpoch”

Seconds since POSIX epoch of 1 Jan 1970 UTC. Note that the EPICS epoch is 631152000 seconds after the POSIX epoch. (cf. POSIX_TIME_AT_EPICS_EPOCH in epicsTime.h from EPICS Base)

“nanoseconds”

Number of nanoseconds since the start of the second.

“timeStamp.userTag”

Extra site-specific information which may provide context for the seconds/nanoseconds value.

alarm_t

struct Alarm

The alarm_t struct

// equivalent
struct alarm_t {
    int32_t severity;
    int32_t status;
    string message;
};
Since

0.1.4

“severity”

Enumeration of 0 - No Alarm, 1 - Minor, 2 - Major, 3 - Invalid.

The meaning of Minor and Major are contextual and may be different for each PV. An Invalid alarm severity means that the value field should not be taken as a meaningful representation of eg. the quantity being measured. Typically, it reflects the most recent valid value.

A UI client may change the state of a widget displaying a value which is alarming by eg. changing border color.

“status”

Enumeration providing context to “severity” 0 - No Alarm, 1 - Device, 2 - Driver, 3 - Record, 4 - Database, 5 - Configuration, 6 - Undefined, 7 - Client

“message”

Arbitrary string describing the condition being alarmed.

NTEnum

Container for a scalar value selection from a list of strings.

struct NTEnum

An enumerated value (choice from a list of strings)

Since

0.1.5

Public Functions

TypeDef build() const

A TypeDef which can be appended.

inline Value create() const

Instantiate.

NTNDArray

Container for image data used by areaDetector.

struct NTNDArray

The areaDetector inspired N-dimension array/image container.

auto def = pvxs::nt::NTNDArray{}.build();
auto value = def.create(); // instantiate a Value

Public Functions

TypeDef build() const

A TypeDef which can be appended.

inline Value create() const

Instantiate.

NTTable

Container for tabular data.

struct NTTable

Columnar data.

Unlike other NT* builders. This create() method returns a Value with the labels field set, and marked. While suitable for an initial value, repeated create() could result in re-sending the same labels array with every update. Users should create() once, and then Value::cloneEmpty() or Value::unmark() for subsequent updates.

Since

1.2.3

Public Functions

NTTable &add_column(TypeCode code, const char *name, const char *label = nullptr)

Append a column

Parameters:

  • code – Value type of column

  • name – Field name of column

  • label – Display label of column. (defaults to field name) Only used in create().

Returns:

this

TypeDef build() const

A TypeDef which can be appended.

Value create() const

Instantiate. Also populates labels list.

NTURI

class NTURI

Public Functions

inline TypeDef build() const

A TypeDef which can be appended.

inline Value create() const

Instantiate.