SettableClock¶

compound module SettableClock

This module represents a settable (step-able) clock with adjustable oscillator compensation.

Extends OscillatorBasedClock with the ability to step the clock time to an explicitly provided value (forward or backward) and to apply a new oscillator-compensation factor. Stepping the clock introduces a discontinuity in the clock-time mapping. Overdue events (whose target time becomes < now after the step) can be handled in three ways:

execute : run overdue events immediately (in order)
skip : drop/cancel overdue events
error : terminate simulation and report an error

The clock time can be set from C++ or by a clock servo module or by a time synchronization protocol or using a <set-clock module=”…” time=”…”/> command in a ScenarioManager script.

See also: IClockServo, ScenarioManager

Usage diagram¶

Inheritance diagram¶

Used in compound modules¶

Name	Type	Description
MultiClock	compound module	Multi-clock aggregator and switch.
EthernetSwitch	compound module	EthernetSwitch models a Layer 2 Ethernet switch with support for various IEEE 802.1 protocols and features. It provides frame forwarding based on MAC addresses and implements multiple switching technologies.

Extends¶

Name	Type	Description
OscillatorBasedClock	compound module	Oscillator-driven clock.

Parameters¶

Name	Type	Default value	Description
displayStringTextFormat	string	“%t (%c)”	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
referenceClock	string	“”	Full path of the reference clock
clockTimeChangeEventSchedulingPriority	int	0	Specifies the scheduling priority of the clock time changed event
emitClockTimeInterval	double	0s	A non-zero value means the clock time will be emitted periodically
oscillatorModule	string	“.oscillator”
initialClockTime	double	0s	Clock time at the simulation time when the module is initialized
roundingMode	string	“up”	When scheduling to a clock time or with a clock delay this clock uses rounding with respect to the nominal tick length
useFutureEventSet	bool	true	true: schedule in FES; false: internal list (requires oscillator signals)
clockGranularity	double	0s	Scheduling grid G; 0s ⇒ use oscillator nominal tick length
initialOscillatorCompensation	double	0ppm
defaultOverdueClockEventHandlingMode	string	“execute”

Properties¶

Name	Value	Description
class	SettableClock
display	i=block/timer

Signals¶

Name	Type	Unit	Description
oscillatorCompensationChanged	double
timeChanged	simtime_t

Statistics¶

Name	Title	Source	Record	Unit	Interpolation Mode	Description
oscillatorCompensationChanged	oscillator compensation		vector	ppm	sample-hold
timeChanged	Clock time	localSignal(timeChanged)	vector	s	linear

Unassigned submodule parameters¶

Name	Type	Default value	Description
oscillator.displayStringTextFormat	string	“%c (%n + %d)”	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
oscillator.emitNumTicksSignal	bool	!parent.useFutureEventSet	Enables emitting a signal at each oscillator tick, can be useful for validating the behavior of the more efficient implementation without events
oscillator.oscillatorTickEventSchedulingPriority	int	0	Specifies the scheduling priority of the tick event
oscillator.nominalTickLength	double		Specifies the elapsed time between oscillator ticks
oscillator.tickOffset	double	0s	Shifts ticks to the past, must be in the range of [0, current tick length)
oscillator.driftRate	double	0ppm	Constant fractional frequency offset
underlyingClock.oscillator.displayStringTextFormat	string	“%c (%n + %d)”	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
underlyingClock.oscillator.emitNumTicksSignal	bool	!parent.useFutureEventSet	Enables emitting a signal at each oscillator tick, can be useful for validating the behavior of the more efficient implementation without events
underlyingClock.oscillator.oscillatorTickEventSchedulingPriority	int	0	Specifies the scheduling priority of the tick event
underlyingClock.oscillator.nominalTickLength	double		Specifies the elapsed time between oscillator ticks
underlyingClock.oscillator.tickOffset	double	0s	Shifts ticks to the past, must be in the range of [0, current tick length)
underlyingClock.oscillator.driftRate	double	0ppm	Constant fractional frequency offset

Source code¶

//
// This module represents a settable (step-able) clock with adjustable oscillator compensation.
//
// Extends ~OscillatorBasedClock with the ability to step the clock time to an explicitly provided value (forward or
// backward) and to apply a new oscillator-compensation factor. Stepping the clock introduces a discontinuity in the
// clock-time mapping. Overdue events (whose target time becomes < now after the step) can be handled in three ways:
//  - execute : run overdue events immediately (in order)
//  - skip    : drop/cancel overdue events
//  - error   : terminate simulation and report an error
//
// The clock time can be set from C++ or by a clock servo module or by a time synchronization protocol or using a
// <set-clock module="..." time="..."/> command in a `ScenarioManager` script.
//
// @see ~IClockServo, ~ScenarioManager
//
module SettableClock extends OscillatorBasedClock
{
    parameters:
        double initialOscillatorCompensation @unit(ppm) = default(0ppm);
        string defaultOverdueClockEventHandlingMode @enum("execute","skip","error") = default("execute");
        @class(SettableClock);
        @signal[oscillatorCompensationChanged](type=double);
        @statistic[oscillatorCompensationChanged](title="oscillator compensation"; record=vector; interpolationmode=sample-hold; unit=ppm);
    submodules:
        underlyingClock: <default("OscillatorBasedClock")> like IClock if typename != "" {
            parameters:
                oscillator.typename = "";
                oscillatorModule = default("^.oscillator");
                useFutureEventSet = default(parent.useFutureEventSet);
                @display("p=100,200");
        }
}

File: src/inet/clock/model/SettableClock.ned