Flow statistics telling how much flow should be sent along a link. More...

#include <station_base.h>

Public Types
typedef std::map< uint32_t, StationID >	SharesMap

Public Member Functions
	FlowStat ()
	Invalid constructor.

	FlowStat (StationID st, uint flow, bool restricted=false)
	Create a FlowStat with an initial entry.

void	AppendShare (StationID st, uint flow, bool restricted=false)
	Add some flow to the end of the shares map.

uint	GetShare (StationID st) const
	Get flow for a station.

void	ChangeShare (StationID st, int flow)
	Change share for specified station.

void	RestrictShare (StationID st)
	Restrict a flow by moving it to the end of the map and decreasing the amount of unrestricted flow.

void	ReleaseShare (StationID st)
	Release ("unrestrict") a flow by moving it to the begin of the map and increasing the amount of unrestricted flow.

void	ScaleToMonthly (uint runtime)
	Scale all shares from link graph's runtime to monthly values.

const SharesMap *	GetShares () const
	Get the actual shares as a const pointer so that they can be iterated over.

uint	GetUnrestricted () const
	Return total amount of unrestricted shares.

void	SwapShares (FlowStat &other)
	Swap the shares maps, and thus the content of this FlowStat with the other one.

StationID	GetViaWithRestricted (bool &is_restricted) const
	Get a station a package can be routed to.

StationID	GetVia () const
	Get a station a package can be routed to.

StationID	GetVia (StationID excluded, StationID excluded2=INVALID_STATION) const
	Get a station a package can be routed to, but exclude the given ones.

void	Invalidate ()
	Reduce all flows to minimum capacity so that they don't get in the way of link usage statistics too much.

Static Public Attributes
static const SharesMap	empty_sharesmap
	Static instance of FlowStat::SharesMap.

Private Attributes
SharesMap	shares
	Shares of flow to be sent via specified station (or consumed locally).

uint	unrestricted
	Limit for unrestricted shares.

Detailed Description

Flow statistics telling how much flow should be sent along a link.

This is done by creating "flow shares" and using std::map's upper_bound() method to look them up with a random number. A flow share is the difference between a key in a map and the previous key. So one key in the map doesn't actually mean anything by itself.

Definition at line 32 of file station_base.h.

Member Typedef Documentation

◆ SharesMap

typedef std::map<uint32_t, StationID> FlowStat::SharesMap

Definition at line 34 of file station_base.h.

Constructor & Destructor Documentation

◆ FlowStat() [1/2]

FlowStat::FlowStat ( )

inline

Invalid constructor.

This can't be called as a FlowStat must not be empty. However, the constructor must be defined and reachable for FlowStat to be used in a std::map.

Definition at line 43 of file station_base.h.

◆ FlowStat() [2/2]

FlowStat::FlowStat	(	StationID	st,
		uint	flow,
		bool	restricted = `false`
	)

inline

Create a FlowStat with an initial entry.

Parameters

st	Station the initial entry refers to.
flow	Amount of flow for the initial entry.
restricted	If the flow to be added is restricted.

Definition at line 51 of file station_base.h.

References shares, and unrestricted.

Member Function Documentation

◆ AppendShare()

void FlowStat::AppendShare	(	StationID	st,
		uint	flow,
		bool	restricted = `false`
	)

inline

Add some flow to the end of the shares map.

Only do that if you know that the station isn't in the map yet. Anything else may lead to inconsistencies.

Parameters

st	Remote station.
flow	Amount of flow to be added.
restricted	If the flow to be added is restricted.

Definition at line 66 of file station_base.h.

References shares, and unrestricted.

Referenced by FlowStatMap::PassOnFlow().

◆ ChangeShare()

void FlowStat::ChangeShare	(	StationID	st,
		int	flow
	)

Change share for specified station.

By specifying INT_MIN as parameter you can erase a share. Newly added flows will be unrestricted.

Parameters

st	Next Hop to be removed.
flow	Share to be added or removed.

Definition at line 4870 of file station_cmd.cpp.

References ReleaseShare(), shares, and unrestricted.

Referenced by FlowStatMap::DeleteFlows(), FlowStatMap::FinalizeLocalConsumption(), and VehicleCargoList::Stage().

◆ GetShare()

uint FlowStat::GetShare ( StationID st ) const

Get flow for a station.

Parameters

st	Station to get flow for.

Returns: Flow for st.

Definition at line 4779 of file station_cmd.cpp.

References shares.

Referenced by FlowStatMap::FinalizeLocalConsumption().

◆ GetShares()

const SharesMap * FlowStat::GetShares ( ) const

inline

Get the actual shares as a const pointer so that they can be iterated over.

Returns: Actual shares.

Definition at line 88 of file station_base.h.

References shares.

Referenced by FlowStatMap::DeleteFlows(), FlowStatMap::FinalizeLocalConsumption(), VehicleCargoList::Stage(), and LinkGraphJob::~LinkGraphJob().

◆ GetUnrestricted()

uint FlowStat::GetUnrestricted ( ) const

inline

Return total amount of unrestricted shares.

Returns: Amount of unrestricted shares.

Definition at line 94 of file station_base.h.

References unrestricted.

◆ GetVia() [1/2]

StationID FlowStat::GetVia ( ) const

inline

Get a station a package can be routed to.

This done by drawing a random number between 0 and sum_shares and then looking that up in the map with lower_bound. So each share gets selected with a probability dependent on its flow. Don't include restricted flows.

Returns: A station ID from the shares map.

Definition at line 130 of file station_base.h.

References RandomRange(), shares, and unrestricted.

Referenced by VehicleCargoList::Stage().

◆ GetVia() [2/2]

StationID FlowStat::GetVia	(	StationID	excluded,
		StationID	excluded2 = `INVALID_STATION`
	)		const

Get a station a package can be routed to, but exclude the given ones.

Parameters

excluded	StationID not to be selected.
excluded2	Another StationID not to be selected.

Returns: A station ID from the shares map.

Definition at line 4798 of file station_cmd.cpp.

References RandomRange(), shares, Swap(), and unrestricted.

◆ GetViaWithRestricted()

StationID FlowStat::GetViaWithRestricted ( bool & is_restricted ) const

inline

Get a station a package can be routed to.

This done by drawing a random number between 0 and sum_shares and then looking that up in the map with lower_bound. So each share gets selected with a probability dependent on its flow. Do include restricted flows here.

Parameters

is_restricted Output if a restricted flow was chosen.

Returns: A station ID from the shares map.

Definition at line 115 of file station_base.h.

References RandomRange(), shares, and unrestricted.

◆ Invalidate()

void FlowStat::Invalidate ( )

Reduce all flows to minimum capacity so that they don't get in the way of link usage statistics too much.

Keep them around, though, to continue routing any remaining cargo.

Definition at line 4851 of file station_cmd.cpp.

References shares, and unrestricted.

◆ ReleaseShare()

void FlowStat::ReleaseShare ( StationID st )

Release ("unrestrict") a flow by moving it to the begin of the map and increasing the amount of unrestricted flow.

Parameters

st	Station of flow to be released.

Definition at line 4951 of file station_cmd.cpp.

References shares, and unrestricted.

Referenced by ChangeShare().

◆ RestrictShare()

void FlowStat::RestrictShare ( StationID st )

Restrict a flow by moving it to the end of the map and decreasing the amount of unrestricted flow.

Parameters

st	Station of flow to be restricted.

Definition at line 4920 of file station_cmd.cpp.

References shares, and unrestricted.

◆ ScaleToMonthly()

void FlowStat::ScaleToMonthly ( uint runtime )

Scale all shares from link graph's runtime to monthly values.

Parameters

runtime Time the link graph has been running without compression.

Precondition: runtime must be greater than 0 as we don't want infinite flow values.

Definition at line 4988 of file station_cmd.cpp.

References shares, and unrestricted.

◆ SwapShares()

void FlowStat::SwapShares ( FlowStat & other )

inline

Swap the shares maps, and thus the content of this FlowStat with the other one.

Parameters

other FlowStat to swap with.

Definition at line 101 of file station_base.h.

References shares, Swap(), and unrestricted.

Field Documentation

◆ empty_sharesmap

const FlowStat::SharesMap FlowStat::empty_sharesmap

static

Static instance of FlowStat::SharesMap.

Note: This instance is created on task start. Lazy creation on first usage results in a data race between the CDist threads.

Definition at line 36 of file station_base.h.

Referenced by FlowEdgeIterator::SetNode().

◆ shares

SharesMap FlowStat::shares

private

Shares of flow to be sent via specified station (or consumed locally).

Definition at line 143 of file station_base.h.

Referenced by AppendShare(), ChangeShare(), FlowStat(), GetShare(), GetShares(), GetVia(), GetVia(), GetViaWithRestricted(), Invalidate(), ReleaseShare(), RestrictShare(), ScaleToMonthly(), and SwapShares().

◆ unrestricted

uint FlowStat::unrestricted

private

Limit for unrestricted shares.

Definition at line 144 of file station_base.h.

Referenced by AppendShare(), ChangeShare(), FlowStat(), GetUnrestricted(), GetVia(), GetVia(), GetViaWithRestricted(), Invalidate(), ReleaseShare(), RestrictShare(), ScaleToMonthly(), and SwapShares().

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

src/station_base.h
src/station_cmd.cpp

Public Types

Public Member Functions

Static Public Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ SharesMap

Constructor & Destructor Documentation

◆ FlowStat() [1/2]

◆ FlowStat() [2/2]

Member Function Documentation

◆ AppendShare()

◆ ChangeShare()

◆ GetShare()

◆ GetShares()

◆ GetUnrestricted()

◆ GetVia() [1/2]

◆ GetVia() [2/2]

◆ GetViaWithRestricted()

◆ Invalidate()

◆ ReleaseShare()

◆ RestrictShare()

◆ ScaleToMonthly()

◆ SwapShares()

Field Documentation

◆ empty_sharesmap

◆ shares

◆ unrestricted