Class Negotiation

Defined in File Negotiation.hpp

Nested Relationships

Nested Types

Class Documentation

class Negotiation

Public Types

enum class SearchStatus

This enumeration describes the status of a search attempt.

Values:

enumerator Deprecated: The requested Table existed, but the requested version is out of date.

enumerator Absent: The requested version of this Table has never been seen by this Negotiation.

enumerator Found: The requested Table has been found.

using VersionedKeySequence = std::vector<VersionedKey>: The versioned key sequence can be used to select tables while demanding specific versions for those tables.

using Proposal = std::vector<Submission>

using Alternatives = std::vector<Itinerary>

using TablePtr = std::shared_ptr<Table>

using ConstTablePtr = std::shared_ptr<const Table>

Public Functions

const std::unordered_set<ParticipantId> &participants() const: Get the participants that are currently involved in this negotiation.

void add_participant(ParticipantId p): Add a new participant to the negotiation. This participant will become involved in the negotiation, and must give its consent for any agreement to be finalized.

bool ready() const: Returns true if at least one proposal is available that has the consent of every participant.

bool complete() const

Returns true if all possible proposals have been received and are ready to be evaluated.

Note that ready() may still be false if complete() is true, in the event that all proposals have been rejected.

TablePtr table(ParticipantId for_participant, const std::vector<ParticipantId> &to_accommodate)

Get a Negotiation::Table that provides a view into what participants are proposing.

This function does not care about table versioning.

See also

find()

Parameters:

for_participant – [in] The participant that is supposed to be viewing this Table. The itineraries of this participant will be left off of the Table.
to_accommodate – [in] The set of participants who are being accommodated at this Table. The ordering of the participants in this set is hierarchical where each participant is accommodating all of the participants that come before it.

ConstTablePtr table(ParticipantId for_participant, const std::vector<ParticipantId> &to_accommodate) const

TablePtr table(const std::vector<ParticipantId> &sequence)

Get a Negotiation::Table that corresponds to the given participant sequence. For a table in terms of for_participant and to_accomodate, you would call: table([to_accommodate…, for_participant])

This function does not care about table versioning.

See also

find()

Parameters:: sequence – [in] The participant sequence that corresponds to the desired table. This is equivalent to [to_accommodate…, for_participant]

ConstTablePtr table(const std::vector<ParticipantId> &sequence) const

SearchResult<TablePtr> find(ParticipantId for_participant, const VersionedKeySequence &to_accommodate)

Find a table, requesting specific versions

See also

table()

SearchResult<ConstTablePtr> find(ParticipantId for_participant, const VersionedKeySequence &to_accommodate) const: const-qualified find()

SearchResult<TablePtr> find(const VersionedKeySequence &sequence)

Find a table, requesting specific versions

See also

table()

SearchResult<ConstTablePtr> find(const VersionedKeySequence &sequence) const: const-qualified find()

ConstTablePtr evaluate(const Evaluator &evaluator) const

Evaluate the proposals that are available.

Returns:: the negotiation table that was considered the best. Call Table::proposal() on this return value to see the full proposal. If there was no

Public Static Functions

static rmf_utils::optional<Negotiation> make(std::shared_ptr<const Viewer> schedule_viewer, std::vector<ParticipantId> participants)

Begin a negotiation.

See also

make_shared()

Parameters:

viewer – [in] A reference to the schedule viewer that represents the most up-to-date schedule.
participants – [in] The participants who are involved in the schedule negotiation.

Returns:

a negotiation between the given participants. If the Viewer is missing a description of any of the participants, then a nullopt will be returned instead.

static std::shared_ptr<Negotiation> make_shared(std::shared_ptr<const Viewer> schedule_viewer, std::vector<ParticipantId> participants)

Begin a negotiation.

See also

make()

Parameters:

viewer – [in] A reference to the schedule viewer that represents the most up-to-date schedule.
participants – [in] The participants who are involved in the schedule negotiation.

Returns:

a negotiation between the given participants. If the Viewer is missing a description of any of the participants, then a nullptr will be returned instead.

class Evaluator

A pure abstract interface class for choosing the best proposal.

Subclassed by rmf_traffic::schedule::QuickestFinishEvaluator

Public Functions

virtual std::size_t choose(const std::vector<const Proposal*> &proposals) const = 0: Given a set of proposals, choose the one that is the “best”. It is up to the implementation of the Evaluator to decide how to rank proposals.

virtual ~Evaluator() = default

template<typename Ptr> struct SearchResult

Public Functions

inline bool deprecated() const

inline bool absent() const

inline bool found() const

inline operator bool() const

Public Members

SearchStatus status: The status of the search.

Ptr table: The Table that was searched for (or nullptr if status is Deprecated or Absent)

struct Submission

Public Members

ParticipantId participant

PlanId plan

Itinerary itinerary

class Table : public std::enable_shared_from_this<Table>

The Negotiation::Table class gives a view of what the other negotiation participants have proposed.

A Table instance is meant to be viewed by a specific participant and displays the proposals of other participants for a specific hierarchies of accommodations. See the documentation of Negotiation::table().

Alongside the views of the other Negotiation participants, the View provided by the Table instance will show the itineraries of schedule participants that are not part of the Negotiation. That way the external itineraries can also be accounted for when planning a submission based on this Table.

Public Types

using ViewerPtr = std::shared_ptr<const Viewer>

Public Functions

ViewerPtr viewer() const: Get a viewer for this Table. The Viewer can be safely used across multiple threads.

const Itinerary *submission() const: Return the submission on this Negotiation Table if it has one.

Version version() const: The a pointer to the latest itinerary version that was submitted to this table, if one was submitted at all.

const Proposal &proposal() const: The proposal on this table so far. This will include the latest itinerary that has been submitted to this Table if anything has been submitted. Otherwise it will only include the submissions that underlie this table.

ParticipantId participant() const: The participant that is meant to submit to this Table.

const VersionedKeySequence &sequence() const: The sequence key that refers to this table. This is equivalent to [to_accommodate…, for_participant]

std::vector<ParticipantId> unversioned_sequence() const: The versioned sequence key that refers to this table.

bool submit(PlanId plan_id, std::vector<Route> itinerary, Version version)

Submit a proposal for a participant that accommodates some of the other participants in the negotiation (or none if an empty vector is given for the to_accommodate argument).

Parameters:

plan_id – [in] A unique identifier for this plan. If this plan is selected by the negotiation, then this ID will be submitted to the traffic schedule as the PlanId for this participant.
itinerary – [in] The itinerary that is being submitted by this participant.
version – [in] A version number assigned to the submission. If this is less or equal to the last version number given, then nothing will change.

Returns:

True if the submission was accepted. False if the version was out of date and nothing changed in the negotiation.

bool reject(Version version, ParticipantId rejected_by, Alternatives alternatives)

Reject the submission of this Negotiation::Table. This indicates that the underlying proposals are infeasible for the Participant of this Table to accommodate. The rejecter should give a set of alternative rollouts that it is capable of. That way the proposer for this Table can submit an itinerary that accommodates it.

Parameters:

version – [in] A version number assigned to the submission. If this is equal to or greater than the last version number given, then this table will be put into a rejected state until a higher proposal version is submitted.
rejected_by – [in] The participant who is rejecting this proposal
alternatives – [in] A set of rollouts that could be used by the participant that is rejecting this proposal. The proposer should use this information to offer a proposal that can accommodate at least one of these rollouts.

Returns:

True if the rejection was accepted. False if the version was out of date and nothing changed in the negotiation.

bool rejected() const: Returns true if the proposal put on this Table has been rejected.

void forfeit(Version version): Give up on this Negotiation Table. This should be called when the participant that is supposed to submit to this Table is unable to find a feasible proposal.

bool forfeited() const: Returns true if the proposer for this Table has forfeited.

bool defunct() const: Returns true if any of this table’s ancestors were rejected or forfeited. When that happens, this Table will no longer have any effect on the Negotiation.

TablePtr respond(ParticipantId by_participant)

If by_participant can respond to this table, then this will return a TablePtr that by_participant can submit a proposal to.

If this function is called before anything has been submitted to this Table, then it will certainly return a nullptr.

ConstTablePtr respond(ParticipantId by_participant) const

TablePtr parent(): Get the parent Table of this Table if it has a parent.

ConstTablePtr parent() const

std::vector<TablePtr> children(): Get the children of this Table if any children exist.

std::vector<ConstTablePtr> children() const

bool ongoing() const: Return true if the negotiation is ongoing (i.e. the Negotiation instance that created this table is still alive). When the Negotiation instance that this Table belongs to has destructed, this will begin to return false.

class Viewer

Public Types

using View = schedule::Viewer::View 

using AlternativeMap = std::unordered_map<ParticipantId, std::shared_ptr<Alternatives>>

Public Functions

View query(const Query::Spacetime &parameters, const VersionedKeySequence &alternatives) const

View this table with the given parameters.

Parameters:

parameters – [in] The spacetime parameters to filter irrelevant routes out of the view
rollouts – [in] The selection of which rollout alternatives should be viewed for the participants who have rejected this proposal in the past.

std::unordered_map<ParticipantId, Endpoint> initial_endpoints(const VersionedKeySequence &alternatives) const: Get the set of initial waypoints for the negotiation participants.

std::unordered_map<ParticipantId, Endpoint> final_endpoints(const VersionedKeySequence &alterantives) const: Get the set of final waypoints for the negotiation participants.

const AlternativeMap &alternatives() const: When a Negotiation::Table is rejected by one of the participants who is supposed to respond, they can offer a set of rollout alternatives. If the proposer can accommodate one of the alternatives for each responding participant, then the negotiation might be able to proceed. This map gives the alternatives for each participant that has provided them.

const Proposal &base_proposals() const: The proposals submitted to the predecessor tables.

std::shared_ptr<const ParticipantDescription> get_description(ParticipantId participant_id) const: Get the description of a participant in this Viewer.

ParticipantId participant_id() const: Get the Participant ID of the participant who should submit to this table.

rmf_utils::optional<ParticipantId> parent_id() const: If the Table has a parent, get its Participant ID.

const VersionedKeySequence &sequence() const: The sequence of the table that is being viewed.

bool defunct() const: Returns true if the table of this viewer is no longer relevant. Unlike the other fields of the Viewer, this is not a snapshot of the table’s state when the Viewer was created; instead this defunct status will remain in sync with the state of the source Table.

bool rejected() const: Returns true if the proposal put on this Table has been rejected.

bool forfeited() const: Returns true if the proposer for this Table has forfeited.

const Itinerary *submission() const: Return the submission on this Negotiation Table if it has one.

std::optional<rmf_traffic::Time> earliest_base_proposal_time() const: The earliest start time of any of the proposals in the table.

std::optional<rmf_traffic::Time> latest_base_proposal_time() const: The latest finish time of any of the proposals in the table.

class Endpoint

View the first or last (depending on context) waypoint in a negotiation participant’s itinerary or alternative.

Public Functions

ParticipantId participant() const: The ID of the participant.

PlanId plan_id() const: The ID of the plan for this endpoint.

RouteId route_id() const: The ID of the route for this endpoint.

const rmf_traffic::Trajectory::Waypoint &waypoint() const: The first or last (depending on context) waypoint.

const std::string &map() const: The map that the endpoint is on.

const ParticipantDescription &description() const: The description of the participant.

struct VersionedKey

This struct is used to select a child table, demaning a specific version.

Public Functions

inline bool operator==(const VersionedKey &other) const

inline bool operator!=(const VersionedKey &other) const

Public Members

ParticipantId participant

Version version