RealtimeContext (BandM signal & music)

java.lang.Object
- eu.bandm.sig.adlib2.RealtimeContext

Direct Known Subclasses:

ConstantRealtimeContext
```
public abstract class RealtimeContext
extends Object
```
Source of information about realtime sampling control flow.
Instances of this interface are created by signal drivers and passed to the computation method Process.step(eu.bandm.sig.adlib2.RealtimeContext) of all concerned signal-related objects.

Rate vs. Period

Constant vs. Variable

Sampling can be equidistant or adaptive, resulting in constant or variable realtime context information. The latter is the unmarked default, the former is represented by the subinterface ConstantRealtimeContext. Signal-related objects indicate which kind they expect and support:
1. A signal-related object whose constructor has a parameter of type ConstantRealtimeContext supports creation-time configuration of realtime information, and expects equivalent information to be passed at every computation step.
2. Any signal-related object whose constructor does not mention type ConstantRealtimeContext is either realtime agnostic or adaptive. The former means that RealtimeContext information passed to Process.step(eu.bandm.sig.adlib2.RealtimeContext) is ignored altogether. The latter means that the object supports different realtime information at every step.
When realtime information varies, each period is understood to start at the step event; i.e., the sampling period reported at a particular invocation of Process.step(eu.bandm.sig.adlib2.RealtimeContext) states the intended realtime interval until the next invocation.

Units

The Java type system does not allow for the specification of dimensions or units of measurement. Thus it cannot be specified whether realtime sampling periods are expressed as multiples of, e.g., seconds, milliseconds, or years.

The values returned by methods of this interface are understood to have the dimensions of time and frequency, respectively. But the units are left unspecified, and subject to agreement between the realtime driver and computations.

For computations that involve constants of time-related dimension, the actual units matter. It is strongly recommended that such computations be documented with respect to the units they assume, such that inconsistencies at interfaces can be detected by the programmer, and corrected via unit conversion.

Conversely, for computations that are invariant with respect to the time unit, it is recommended to mention only abstract time units in the documentation.

Extreme Values

Implicit Conversion

Signal Probe

Constructor Summary

Constructors
Constructor and Description

RealtimeContext()

Constructors
Constructor and Description
`RealtimeContext()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`double`	`getSamplingPeriodAsDouble()` Returns the projected sampling period as a `double` value.
`float`	`getSamplingPeriodAsFloat()` Returns the projected sampling period as a `float` value.
`abstract IntFraction`	`getSamplingPeriodAsInt()`
`abstract LongFraction`	`getSamplingPeriodAsLong()`
`abstract int`	`getSamplingPeriodPerRateAsInt()` Returns the projected sampling period as a `int` value.
`long`	`getSamplingPeriodPerRateAsLong()` Returns the projected sampling period as a `long` value.
`double`	`getSamplingRateAsDouble()` Returns the projected sampling rate as a `double` value.
`float`	`getSamplingRateAsFloat()` Returns the projected sampling rate as a `float` value.
`abstract IntFraction`	`getSamplingRateAsInt()`
`abstract LongFraction`	`getSamplingRateAsLong()`
`abstract int`	`getSamplingRatePerPeriodAsInt()` Returns the projected sampling rate as a `int` value.
`long`	`getSamplingRatePerPeriodAsLong()` Returns the projected sampling rate as a `long` value.
`SignalProbe<Object>`	`getSignalProbe()`
`boolean`	`isRational()`
`void`	`setSignalProbe(SignalProbe<Object> signalProbe)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RealtimeContext
```
public RealtimeContext()
```
- Method Detail
  - getSamplingRateAsDouble
```
public double getSamplingRateAsDouble()
```
    Returns the projected sampling rate as a double value.
    The returned value is the expected number of clock tick events per unit of time, extrapolated from the interval between the current and the next event.
    The value should be the reciprocal of the value returned by getSamplingPeriodAsDouble(). It should be finite, non-negative, and equal to 0.0 for one-off events that do not repeat.
    The default implementation simply returns 1 / getSamplingPeriodAsDouble(). Subclasses must override at least one of the two methods in order to avoid indefinite recursion.
    Note that the same quantity can also be represented as a float value (getSamplingRateAsFloat()). Special care should be taken if the intended value loses significant precision in float format.
    
    See Also:
    
    getSamplingRateAsFloat(), getSamplingPeriodAsDouble()
  - getSamplingPeriodAsDouble
```
public double getSamplingPeriodAsDouble()
```
    Returns the projected sampling period as a double value.
    The returned value is the expected multiple of unit time elapsing per clock tick event, extrapolated from the interval between the current and the next event.
    The value should be the reciprocal of the value returned by getSamplingRateAsDouble(). It should be positive, and equal to POSITIVE_INFINITY for one-off events that do not repeat.
    The default implementation simply returns 1 / getSamplingRateAsDouble(). Subclasses must override at least one of the two methods in order to avoid indefinite recursion.
    Note that the same quantity can also be represented as a float value (getSamplingPeriodAsFloat()). Special care should be taken if the intended value loses significant precision in float format.
    
    See Also:
    
    getSamplingPeriodAsFloat(), getSamplingRateAsDouble()
  - getSamplingRateAsFloat
```
public float getSamplingRateAsFloat()
```
    Returns the projected sampling rate as a float value.
    The returned value is the expected number of clock tick events per unit of time, extrapolated from the interval between the current and the next event.
    The value should be the reciprocal of the value returned by getSamplingPeriodAsFloat(). It should be finite, non-negative, and exactly 0.0 for one-off events that do not repeat.
    The default implementation simply returns 1 / getSamplingPeriodAsFloat(). Subclasses must override at least one of the two methods in order to avoid indefinite recursion.
    Note that the same quantity can also be represented as a double value (getSamplingRateAsDouble()). Special care should be taken if the intended value loses significant precision in float format.
    
    See Also:
    
    getSamplingRateAsDouble(), getSamplingPeriodAsFloat()
  - getSamplingPeriodAsFloat
```
public float getSamplingPeriodAsFloat()
```
    Returns the projected sampling period as a float value.
    The returned value is the expected multiple of unit time elapsing per clock tick event, extrapolated from the interval between the current and the next event.
    The value should be the reciprocal of the value returned by getSamplingRateAsFloat(). It should be positive, and equal to POSITIVE_INFINITY for one-off events that do not repeat.
    The default implementation simply returns 1 / getSamplingRateAsFloat(). Subclasses must override at least one of the two methods in order to avoid indefinite recursion.
    Note that the same quantity can also be represented as a double value (getSamplingPeriodAsDouble()). Special care should be taken if the intended value loses significant precision in float format.
    
    See Also:
    
    getSamplingPeriodAsDouble(), getSamplingRateAsFloat()
  - getSamplingRatePerPeriodAsInt
```
public abstract int getSamplingRatePerPeriodAsInt()
```
    Returns the projected sampling rate as a int value.
    The returned value is the expected integral number of clock tick events per some integral multiple of unit of time specified by getSamplingPeriodPerRateAsInt(), extrapolated from the interval between the current and the next event.
    The returned value bears no fixed relationship to unit frequency by itself. It should be non-negative, and equal to 0 for one-off events that do not repeat.
    The rational number r = getSamplingRatePerPeriodAsInt() / getSamplingPeriodPerRateAsInt() should be approximated by the values returned by getSamplingRateAsFloat() and getSamplingRateAsDouble(). Approximations may be adequate for numerical computations, but discrete computations should always use the exact rational number.
    Note that the name of this method does not imply that the returned value specifies a rate divided by a period. Rather, it specifies a rate as a number of events measured in a reference period specified elsewhere.
    Note that the same quantity can also be represented as a long value (getSamplingRatePerPeriodAsLong()). Special care should be taken if the intended value is prone to overflow in int format.
    
    See Also:
    
    getSamplingRatePerPeriodAsLong(), getSamplingPeriodPerRateAsInt()
  - getSamplingPeriodPerRateAsInt
```
public abstract int getSamplingPeriodPerRateAsInt()
```
    Returns the projected sampling period as a int value.
    The returned value is the expected integral multiple of unit time required for some integral number of clock tick events specified by getSamplingRatePerPeriodAsInt(), extrapolated from the interval between the current and the next event.
    The returned value bears no fixed relationship to unit time by itself. It should be non-negative. The value is irrelevant and should be normalized to 1 for one-off events that do not repeat.
    The rational number p = getSamplingPeriodPerRateAsInt() / getSamplingRatePerPeriodAsInt() should be approximated by the values returned by getSamplingPeriodAsFloat() and getSamplingPeriodAsDouble(). Approximations may be adequate for numerical computations, but discrete computations should always use the exact rational number.
    Note that the name of this method does not imply that the returned value specifies a rate divided by a period. Rather, it specifies a rate as a number of events measured in a reference period specified elsewhere.
    Note that the same quantity can also be represented as a long value (getSamplingPeriodPerRateAsLong()). Special care should be taken if the intended value is prone to overflow in int format.
    
    See Also:
    
    getSamplingPeriodPerRateAsLong(), getSamplingRatePerPeriodAsInt()
  - getSamplingRatePerPeriodAsLong
```
public long getSamplingRatePerPeriodAsLong()
```
    Returns the projected sampling rate as a long value.
    The returned value is the expected integral number of clock tick events per some integral multiple of unit of time specified by getSamplingPeriodPerRateAsLong(), extrapolated from the interval between the current and the next event.
    The returned value bears no fixed relationship to unit frequency by itself. It should be non-negative, and equal to 0 for one-off events that do not repeat.
    The rational number r = getSamplingRatePerPeriodAsLong() / getSamplingPeriodPerRateAsLong() should be approximated by the values returned by getSamplingRateAsFloat() and getSamplingRateAsDouble(). Approximations may be adequate for numerical computations, but discrete computations should always use the exact rational number.
    Note that the name of this method does not imply that the returned value specifies a rate divided by a period. Rather, it specifies a rate as a number of events measured in a reference period specified elsewhere.
    Note that the same quantity can also be represented as a int value (getSamplingRatePerPeriodAsInt()). Special care should be taken if the intended value is prone to overflow in int format.
    
    See Also:
    
    getSamplingRatePerPeriodAsInt(), getSamplingPeriodPerRateAsLong()
  - getSamplingPeriodPerRateAsLong
```
public long getSamplingPeriodPerRateAsLong()
```
    Returns the projected sampling period as a long value.
    The returned value is the expected integral multiple of unit time required for some integral number of clock tick events specified by getSamplingRatePerPeriodAsLong(), extrapolated from the interval between the current and the next event.
    The returned value bears no fixed relationship to unit time by itself. It should be non-negative. The value is irrelevant and should be normalized to 1 for one-off events that do not repeat.
    The rational number p = getSamplingPeriodPerRateAsLong() / getSamplingRatePerPeriodAsLong() should be approximated by the values returned by getSamplingPeriodAsFloat() and getSamplingPeriodAsDouble(). Approximations may be adequate for numerical computations, but discrete computations should always use the exact rational number.
    Note that the name of this method does not imply that the returned value specifies a rate divided by a period. Rather, it specifies a rate as a number of events measured in a reference period specified elsewhere.
    Note that the same quantity can also be represented as a int value (getSamplingPeriodPerRateAsInt()). Special care should be taken if the intended value is prone to overflow in int format.
    
    See Also:
    
    getSamplingPeriodPerRateAsInt(), getSamplingRatePerPeriodAsLong()
  - getSamplingPeriodAsInt
```
public abstract IntFraction getSamplingPeriodAsInt()
```
  - getSamplingRateAsInt
```
public abstract IntFraction getSamplingRateAsInt()
```
  - getSamplingPeriodAsLong
```
public abstract LongFraction getSamplingPeriodAsLong()
```
  - getSamplingRateAsLong
```
public abstract LongFraction getSamplingRateAsLong()
```
  - isRational
```
public boolean isRational()
```
  - setSignalProbe
```
public void setSignalProbe(SignalProbe<Object> signalProbe)
```
  - getSignalProbe
```
public SignalProbe<Object> getSignalProbe()
```

Class RealtimeContext

Rate vs. Period

Constant vs. Variable

Units

Extreme Values

Implicit Conversion

Signal Probe

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RealtimeContext

Method Detail

getSamplingRateAsDouble

getSamplingPeriodAsDouble

getSamplingRateAsFloat

getSamplingPeriodAsFloat

getSamplingRatePerPeriodAsInt

getSamplingPeriodPerRateAsInt

getSamplingRatePerPeriodAsLong

getSamplingPeriodPerRateAsLong

getSamplingPeriodAsInt

getSamplingRateAsInt

getSamplingPeriodAsLong

getSamplingRateAsLong

isRational

setSignalProbe

getSignalProbe