scheduling

package
v3.21.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2022 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package scheduling implements a packet scheduling that detects and avoids conflicts and enforces regional restrictions like duty-cycle and dwell time.

Index

Constants

This section is empty.

Variables

View Source
var (
	// QueueDelay indicates the time the gateway needs to recharge the concentrator between items in the queue.
	// This is a conservative value as implemented in the Semtech UDP Packet Forwarder reference implementation,
	// see https://github.com/Lora-net/packet_forwarder/blob/v4.0.1/lora_pkt_fwd/src/jitqueue.c#L39
	QueueDelay = 30 * time.Millisecond

	// ScheduleTimeShort is a short time to send a downlink message to the gateway before it has to be transmitted.
	// This time is comprised of a lower network latency and QueueDelay. This delay is used to block scheduling when the
	// schedule time to the estimated concentrator time is less than this value, see ScheduleAt.
	ScheduleTimeShort = 100*time.Millisecond + QueueDelay

	// ScheduleTimeLong is a long time to send a downlink message to the gateway before it has to be transmitted.
	// This time is comprised of a higher network latency and QueueDelay. This delay is used for pseudo-immediate
	// scheduling, see ScheduleAnytime.
	ScheduleTimeLong = 500*time.Millisecond + QueueDelay
)
View Source
var DutyCycleWindow = 1 * time.Hour

DutyCycleWindow is the window in which duty-cycle is enforced. A lower value results in balancing capacity in time, while a higher value allows for bursts.

View Source
var SystemTimeSource = &systemTimeSource{}

SystemTimeSource is a TimeSource that uses the local system time.

Functions

This section is empty.

Types

type Clock

type Clock interface {
	// IsSynced returns whether the clock is synchronized.
	IsSynced() bool
	// SyncTime returns the server time of the last sync.
	// This method returns false if the clock is not synchronized.
	SyncTime() (time.Time, bool)
	// FromServerTime returns an indication of the concentrator time at the given server time.
	FromServerTime(time.Time) (ConcentratorTime, bool)
	// ToServerTime returns an indication of the server time at the given concentrator time.
	ToServerTime(ConcentratorTime) time.Time
	// FromGatewayTime returns an indication of the concentrator time at the given gateway time if available.
	FromGatewayTime(time.Time) (ConcentratorTime, bool)
	// FromTimestampTime returns the concentrator time for the given timestamp.
	FromTimestampTime(timestamp uint32) ConcentratorTime
}

Clock represents an absolute time source.

type ConcentratorTime

type ConcentratorTime int64

ConcentratorTime is the time relative to the concentrator start time (nanoseconds).

type DutyCycleCeilings

type DutyCycleCeilings map[ttnpb.TxSchedulePriority]float32

DutyCycleCeilings contains the upper limits per schedule priority. The limit is a fraction of the duty-cycle.

DefaultDutyCycleCeilings contains the default duty-cycle ceilings per schedule priority.

type Emission

type Emission struct {
	// contains filtered or unexported fields
}

Emission contains the scheduled time and duration of an emission.

func NewEmission

func NewEmission(starts ConcentratorTime, duration time.Duration) Emission

NewEmission returns a new Emission with the given values.

func (Emission) AfterWithOffAir

func (em Emission) AfterWithOffAir(other Emission, toa frequencyplans.TimeOffAir) time.Duration

AfterWithOffAir returns the time between the end of the given other emission to the start of this emission, considering time-off-air.

func (Emission) BeforeWithOffAir

func (em Emission) BeforeWithOffAir(other Emission, toa frequencyplans.TimeOffAir) time.Duration

BeforeWithOffAir returns the time between the end of this emission to the start of the given other emission, considering time-off-air.

func (Emission) Duration

func (em Emission) Duration() time.Duration

Duration returns the duration of the emission.

func (Emission) Ends

func (em Emission) Ends() ConcentratorTime

Ends returns the time when the emission ends.

func (Emission) EndsWithOffAir

func (em Emission) EndsWithOffAir(toa frequencyplans.TimeOffAir) ConcentratorTime

EndsWithOffAir returns the time when the emission ends plus the time-off-air.

func (Emission) OffAir

OffAir returns the time-off-air of the emission.

func (Emission) OverlapsWithOffAir

func (em Emission) OverlapsWithOffAir(other Emission, toa frequencyplans.TimeOffAir) bool

OverlapsWithOffAir returns whether the given emission overlaps with this emission, considering time-off-air.

func (Emission) Starts

func (em Emission) Starts() ConcentratorTime

Starts returns the time when the emission starts.

func (Emission) Within

func (em Emission) Within(from, to ConcentratorTime) time.Duration

Within returns the duration of the emission that happens within the given window.

type Emissions

type Emissions []Emission

Emissions is an list of emissions.

func (Emissions) GreaterThan added in v3.10.5

func (ems Emissions) GreaterThan(to ConcentratorTime) Emissions

GreaterThan returns a new list of emissions that have not ended relative to the provided time.

func (Emissions) Insert

func (ems Emissions) Insert(em Emission) Emissions

Insert inserts the given emission to the emissions by preserving order.

type Options added in v3.9.0

type Options struct {
	PayloadSize int
	*ttnpb.TxSettings
	RTTs        RTTs
	Priority    ttnpb.TxSchedulePriority
	UplinkToken *ttnpb.UplinkToken
}

Options define options for scheduling downlink.

type RTTs

type RTTs interface {
	Stats(percentile int, ref time.Time) (min, max, median, np time.Duration, count int)
}

RTTs provides round-trip times.

type RolloverClock

type RolloverClock struct {
	// contains filtered or unexported fields
}

RolloverClock is a Clock that takes roll-over of a uint32 microsecond concentrator time into account.

func (*RolloverClock) FromGatewayTime

func (c *RolloverClock) FromGatewayTime(gateway time.Time) (ConcentratorTime, bool)

FromGatewayTime implements Clock.

func (*RolloverClock) FromServerTime

func (c *RolloverClock) FromServerTime(server time.Time) (ConcentratorTime, bool)

FromServerTime implements Clock.

func (*RolloverClock) FromTimestampTime

func (c *RolloverClock) FromTimestampTime(timestamp uint32) ConcentratorTime

FromTimestampTime implements Clock.

func (*RolloverClock) IsSynced

func (c *RolloverClock) IsSynced() bool

IsSynced implements Clock.

func (*RolloverClock) Sync

func (c *RolloverClock) Sync(timestamp uint32, server time.Time) ConcentratorTime

Sync synchronizes the clock with the given concentrator timestamp and the server time.

func (*RolloverClock) SyncTime added in v3.9.0

func (c *RolloverClock) SyncTime() (time.Time, bool)

SyncTime implements Clock.

func (*RolloverClock) SyncWithGatewayAbsolute

func (c *RolloverClock) SyncWithGatewayAbsolute(timestamp uint32, server, gateway time.Time) ConcentratorTime

SyncWithGatewayAbsolute synchronizes the clock with the given concentrator timestamp, the server time and the absolute gateway time that corresponds to the given timestamp.

func (*RolloverClock) SyncWithGatewayConcentrator

func (c *RolloverClock) SyncWithGatewayConcentrator(timestamp uint32, server time.Time, gateway *time.Time, concentrator ConcentratorTime) ConcentratorTime

SyncWithGatewayConcentrator synchronizes the clock with the given concentrator timestamp, the server time and the relative gateway time that corresponds to the given timestamp.

func (*RolloverClock) ToServerTime

func (c *RolloverClock) ToServerTime(t ConcentratorTime) time.Time

ToServerTime implements Clock.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler is a packet scheduler that takes time conflicts and sub-band restrictions into account.

func NewScheduler

func NewScheduler(ctx context.Context, fps map[string]*frequencyplans.FrequencyPlan, enforceDutyCycle bool, scheduleAnytimeDelay *time.Duration, timeSource TimeSource) (*Scheduler, error)

NewScheduler instantiates a new Scheduler for the given frequency plan. If no time source is specified, the system time is used.

func (*Scheduler) IsGatewayTimeSynced

func (s *Scheduler) IsGatewayTimeSynced() bool

IsGatewayTimeSynced reports whether scheduler clock is synchronized with gateway time.

func (*Scheduler) Now

func (s *Scheduler) Now() (ConcentratorTime, bool)

Now returns an indication of the current concentrator time. This method returns false if the clock is not synced with the server.

func (*Scheduler) ScheduleAnytime

func (s *Scheduler) ScheduleAnytime(ctx context.Context, opts Options) (res Emission, now ConcentratorTime, err error)

ScheduleAnytime attempts to schedule the given Tx settings with the given priority from the time in the settings. If there are round-trip times available, the maximum value will be used instead of ScheduleTimeShort. This method returns the emission.

The scheduler does not support immediate scheduling, i.e. sending a message to the gateway that should be transmitted immediately. The reason for this is that this scheduler cannot determine conflicts or enforce duty-cycle when the emission time is unknown. Therefore, when the time is set to Immediate, the estimated current concentrator time plus ScheduleDelayLong will be used.

func (*Scheduler) ScheduleAt

func (s *Scheduler) ScheduleAt(ctx context.Context, opts Options) (res Emission, now ConcentratorTime, err error)

ScheduleAt attempts to schedule the given Tx settings with the given priority. If there are round-trip times available, the nth percentile (n = scheduleLateRTTPercentile) value will be used instead of ScheduleTimeShort.

func (*Scheduler) SubBandCount

func (s *Scheduler) SubBandCount() int

SubBandCount returns the number of sub bands in the scheduler.

func (*Scheduler) SubBandStats added in v3.9.0

func (s *Scheduler) SubBandStats() []*ttnpb.GatewayConnectionStats_SubBand

SubBandStats returns a map with the usage stats of each sub band.

func (*Scheduler) Sync

func (s *Scheduler) Sync(v uint32, server time.Time) ConcentratorTime

Sync synchronizes the clock with the given concentrator time v and the server time.

func (*Scheduler) SyncWithGatewayAbsolute

func (s *Scheduler) SyncWithGatewayAbsolute(timestamp uint32, server, gateway time.Time) ConcentratorTime

SyncWithGatewayAbsolute synchronizes the clock with the given concentrator timestamp, the server time and the absolute gateway time that corresponds to the given timestamp.

func (*Scheduler) SyncWithGatewayConcentrator

func (s *Scheduler) SyncWithGatewayConcentrator(timestamp uint32, server time.Time, gateway *time.Time, concentrator ConcentratorTime) ConcentratorTime

SyncWithGatewayConcentrator synchronizes the clock with the given concentrator timestamp, the server time and the relative gateway time that corresponds to the given timestamp.

func (*Scheduler) TimeFromServerTime added in v3.16.0

func (s *Scheduler) TimeFromServerTime(t time.Time) (ConcentratorTime, bool)

TimeFromServerTime returns an indication of the provided timestamp in concentrator time. This method returns false if the clock is not synced with the server.

func (*Scheduler) TimeFromTimestampTime

func (s *Scheduler) TimeFromTimestampTime(t uint32) (ConcentratorTime, bool)

TimeFromTimestampTime returns the concentrator time by the given timestamp. This method returns false if the clock is not synced with the server.

type SubBand

type SubBand struct {
	SubBandParameters
	// contains filtered or unexported fields
}

SubBand tracks the utilization and controls the duty-cycle of a sub-band.

func NewSubBand

func NewSubBand(params SubBandParameters, clock Clock, ceilings DutyCycleCeilings) *SubBand

NewSubBand returns a new SubBand considering the given duty-cycle, clock and optionally duty-cycle ceilings.

func (*SubBand) DutyCycleUtilization

func (sb *SubBand) DutyCycleUtilization() float32

DutyCycleUtilization returns the utilization as a fraction of the available duty-cycle.

func (*SubBand) HasOverlap

func (sb *SubBand) HasOverlap(subBand *SubBand) bool

HasOverlap checks if the two sub bands have an overlap.

func (*SubBand) IsIdentical

func (sb *SubBand) IsIdentical(subBand *SubBand) bool

IsIdentical checks if the two sub bands are identical.

func (*SubBand) Schedule

func (sb *SubBand) Schedule(em Emission, p ttnpb.TxSchedulePriority) error

Schedule schedules the given emission with the priority. If there is no time available due to duty-cycle limitations, an error with code ResourceExhausted is returned.

func (*SubBand) ScheduleAnytime

func (sb *SubBand) ScheduleAnytime(d time.Duration, next func() ConcentratorTime, p ttnpb.TxSchedulePriority) (Emission, error)

ScheduleAnytime schedules the given duration at a time when there is availability by accounting for duty-cycle. The given next callback should return the next option that does not conflict with other scheduled downlinks. If there is no duty-cycle limitation, this method returns the first option.

type SubBandParameters

type SubBandParameters struct {
	MinFrequency,
	MaxFrequency uint64
	DutyCycle float32
}

SubBandParameters defines the sub-band frequency bounds and duty-cycle value.

func (SubBandParameters) Comprises

func (sb SubBandParameters) Comprises(frequency uint64) bool

Comprises returns whether the given frequency falls in the sub-band.

type TimeSource

type TimeSource interface {
	Now() time.Time
}

TimeSource is a source for getting a current time.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL