Class Database

Inheritance Relationships

Base Types

Class Documentation

class Database : public rmf_traffic::schedule::ItineraryViewer, public rmf_traffic::schedule::Writer, public rmf_traffic::schedule::Snappable

A class that maintains a database of scheduled Trajectories. This class is intended to be used only for the canonical RMF traffic schedule database.

The Viewer API can be queried to find Trajectories that match certain criteria.

You can also retrieve update patches from a database. To apply those patches to a downstream Viewer, it is strongly advised to use the rmf_traffic::schedule::Mirror class.

Public Functions

virtual void set(ParticipantId participant, PlanId plan, const Itinerary &itinerary, StorageId storage_base, ItineraryVersion version) final

Set a brand new itinerary for a participant. This will replace any itinerary that is already in the schedule for the participant.

Parameters:

  • participant – [in] The ID of the participant whose itinerary is being updated.

  • plan – [in] The ID of the plan that this new itinerary belongs to.

  • itinerary – [in] The new itinerary of the participant.

  • storage_base – [in] The storage index offset that the database should use for this plan. This should generally be the integer number of total routes that the participant has ever given to the writer prior to setting this new itinerary. This value helps ensure consistent unique IDs for every route, even after a database has failed over or restarted.

  • version – [in] The version for this itinerary change.

virtual void extend(ParticipantId participant, const Itinerary &routes, ItineraryVersion version) final

Add a set of routes to the itinerary of this participant.

Parameters:

  • participant – [in] The ID of the participant whose itinerary is being updated.

  • routes – [in] The set of routes that should be added to the itinerary.

  • version – [in] The version for this itinerary change

virtual void delay(ParticipantId participant, Duration delay, ItineraryVersion version) final

Add a delay to the itinerary from the specified Time.

Nothing about the routes in the itinerary will be changed except that waypoints will shifted through time.

Parameters:

  • participant – [in] The ID of the participant whose itinerary is being delayed.

  • delay – [in] This is the duration of time to delay all qualifying Trajectory Waypoints.

  • version – [in] The version for this itinerary change

virtual void reached(ParticipantId participant, PlanId plan, const std::vector<CheckpointId> &reached_checkpoints, ProgressVersion version) final

Indicate that a participant has reached certain checkpoints.

Parameters:

  • participant – [in] The ID of the participant whose progress is being set.

  • plan – [in] The ID of the plan which progress has been made for.

  • reached_checkpoints – [in] The set of checkpoints that have been reached. The indices in the vector must correspond to the RouteIds of the plan.

  • version – [in] The version number for this progress.

virtual void clear(ParticipantId participant, ItineraryVersion version) final

Erase an itinerary from this database.

Parameters:

  • participant – [in] The ID of the participant whose itinerary is being erased.

  • version – [in] The version for this itinerary change

virtual Registration register_participant(ParticipantDescription participant_info) final

Register a new participant.

Parameters:

  • participant_info – [in] Information about the new participant.

  • time – [in] The time at which the registration is being requested.

Returns:

result of registering the new participant.

virtual void update_description(ParticipantId participant, ParticipantDescription desc) final

Updates a participants footprint

Parameters:

  • participant – [in] The ID of the participant to update

  • desc – [in] The participant description

virtual void unregister_participant(ParticipantId participant) final

Before calling this function on a Database, you should set the current time for the database by calling set_current_time(). This will allow the database to cull this participant after a reasonable amount of time has passed.

virtual View query(const Query &parameters) const final

Query this Viewer to get a View of the Trajectories inside of it that match the Query parameters.

virtual View query(const Query::Spacetime &spacetime, const Query::Participants &participants) const final

Alternative signature for query()

virtual const std::unordered_set<ParticipantId> &participant_ids() const final

Get the set of active participant IDs.

std::shared_ptr<const ParticipantDescription> get_participant(std::size_t participant_id) const final
Version latest_version() const
std::optional<ItineraryView> get_itinerary(std::size_t participant_id) const final
std::optional<PlanId> get_current_plan_id(std::size_t participant_id) const final
virtual const std::vector<CheckpointId> *get_current_progress(ParticipantId participant_id) const final

Get the current progress of a specific participant. If a participant with the specified ID is not registered with the schedule or has never made progress, then this will return a nullptr.

virtual ProgressVersion get_current_progress_version(ParticipantId participant_id) const final

Get the current known progress of a specific participant along its current plan. If no progress has been made, this will have a value of 0.

virtual DependencySubscription watch_dependency(Dependency dependency, std::function<void()> on_reached, std::function<void()> on_deprecated) const final

Watch a traffic dependency. When a relevant event happens for the dependency, the on_reached or on_deprecated will be triggered. If the event had already come to pass before this function is called, then the relevant callback will be triggered right away, within the scope of this function.

Only one of the callbacks will ever be triggered, and it will only be triggered at most once.

Parameters:

  • on_reached – [in] If the dependency is reached, this will be triggered. on_changed will never be triggered afterwards.

  • on_deprecated – [in] If the plan of the participant changed before it reached this dependency then the dependency is deprecated and this callback will be triggered. on_reached will never be triggered afterwards.

Returns:

an object that maintains the dependency for the viewer.

virtual std::shared_ptr<const Snapshot> snapshot() const final

Get a snapshot of the schedule.

Database()

Initialize a Database.

const Inconsistencies &inconsistencies() const

A description of all inconsistencies currently present in the database. Inconsistencies are isolated between Participants.

To fix the inconsistency, the Participant should resend every Itinerary change that was missing from every range, or else send a change that nullifies all previous changes, such as a set(~) or erase(ParticipantId).

Patch changes(const Query &parameters, std::optional<Version> after) const

Get the changes in this Database that match the given Query parameters. If a version number is specified, then the returned Patch will reflect the changes that occurred from the specified version to the current version of the schedule.

To get a consistent reflection of the schedule when specifying a base version, it is important that the query parameters are not changed in between calls.

Parameters:

  • parameters – [in] The parameters describing what types of schedule entries the mirror cares about.

  • after – [in] Specify that only changes which come after this version number are desired. If you give a nullopt for this argument, then all changes will be provided.

Returns:

A Patch of schedule changes that are relevant to the specified query parameters.

View query(const Query &parameters, Version after) const

View the routes that match the parameters and have changed (been added or delayed) since the specified version. This is useful for viewing incremental changes.

Parameters:

  • parameters – [in] The parameters describing what types of schedule entries are relevant.

  • after – [in] Specify that only routes which changed after this version number are desired.

Returns:

a view of the routes that are different since the specified version.

void set_maximum_cumulative_delay(rmf_traffic::Duration maximum_delay)

Excessive cumulative delays have a risk of overloading the schedule database by taking up an excessive amount of memory to track the delay history. Typically this would be a cumulative delay on the scale of weeks, months, years, etc, and almost certainly indicates an error in the schedule participant’s reporting.

Still, to avoid harmful effects of participant errors, when the database detects an excessive cumulative delay for a participant, a new delay(~) command will be converted into a set(~) command. This function lets you decide what the threshold should be for that. The default is equivalent to 2 hours.

std::optional<rmf_traffic::Duration> get_cumulative_delay(ParticipantId participant) const

Get the current cumulative delay for the participant.

Version cull(Time time)

Throw away all itineraries up to the specified time.

Parameters:

time – [in] All Trajectories that finish before this time will be culled from the Database. Their data will be completely deleted from this Database object.

Returns:

The new version of the schedule database. If nothing was culled, this version number will remain the same.

void set_current_time(Time time)

Set the current time on the database. This should be used immediately before calling unregister_participant() so that the database can cull the existence of the participant at an appropriate time. There’s no need to call this function for any other purpose.

ItineraryVersion itinerary_version(ParticipantId participant) const

Get the current itinerary version for the specified participant.

PlanId latest_plan_id(ParticipantId participant) const

Get the last Plan ID used by this participant.

This provides the same information as get_current_plan_id, except it throws an exception instead of returning an optional if the participant does not exist.

StorageId next_storage_base(ParticipantId participant) const

Get the last Storage ID used by this participant.