Program Listing for File Negotiation.hpp

↰ Return to documentation for file (include/rmf_traffic/schedule/Negotiation.hpp)

/*
 * Copyright (C) 2020 Open Source Robotics Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
*/

#ifndef RMF_TRAFFIC__SCHEDULE__NEGOTIATION_HPP
#define RMF_TRAFFIC__SCHEDULE__NEGOTIATION_HPP

#include <rmf_traffic/schedule/Viewer.hpp>
#include <rmf_utils/impl_ptr.hpp>

#include <unordered_map>

namespace rmf_traffic {
namespace schedule {

//==============================================================================
class Negotiation
{
public:

  // TODO(MXG): Add an API that allows a multi-participant planner to propose
  // globally optimal itineraries.

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

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

  const std::unordered_set<ParticipantId>& participants() const;

  void add_participant(ParticipantId p);

  bool ready() const;

  bool complete() const;

  struct VersionedKey
  {
    ParticipantId participant;
    Version version;

    inline bool operator==(const VersionedKey& other) const
    {
      return participant == other.participant
        && version == other.version;
    }

    inline bool operator!=(const VersionedKey& other) const
    {
      return !(*this == other);
    }
  };

  using VersionedKeySequence = std::vector<VersionedKey>;

  struct Submission
  {
    ParticipantId participant;
    PlanId plan;
    Itinerary itinerary;
  };

  using Proposal = std::vector<Submission>;
  using Alternatives = std::vector<Itinerary>;

  class Table;
  using TablePtr = std::shared_ptr<Table>;
  using ConstTablePtr = std::shared_ptr<const Table>;

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

    class Viewer
    {
    public:

      using View = schedule::Viewer::View;

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

      class Endpoint
      {
      public:

        ParticipantId participant() const;

        PlanId plan_id() const;

        RouteId route_id() const;

        const rmf_traffic::Trajectory::Waypoint& waypoint() const;

        const std::string& map() const;

        const ParticipantDescription& description() const;

        class Implementation;
      private:
        Endpoint();
        rmf_utils::impl_ptr<Implementation> _pimpl;
      };

      std::unordered_map<ParticipantId, Endpoint> initial_endpoints(
        const VersionedKeySequence& alternatives) const;

      std::unordered_map<ParticipantId, Endpoint> final_endpoints(
        const VersionedKeySequence& alterantives) const;

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

      const AlternativeMap& alternatives() const;

      const Proposal& base_proposals() const;

      std::shared_ptr<const ParticipantDescription> get_description(
        ParticipantId participant_id) const;

      ParticipantId participant_id() const;

      rmf_utils::optional<ParticipantId> parent_id() const;

      const VersionedKeySequence& sequence() const;

      bool defunct() const;

      bool rejected() const;

      bool forfeited() const;

      const Itinerary* submission() const;

      std::optional<rmf_traffic::Time> earliest_base_proposal_time() const;

      std::optional<rmf_traffic::Time> latest_base_proposal_time() const;

      class Implementation;
    private:
      Viewer();
      rmf_utils::impl_ptr<Implementation> _pimpl;
    };

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

    ViewerPtr viewer() const;

    const Itinerary* submission() const;

    Version version() const;

    const Proposal& proposal() const;

    ParticipantId participant() const;

    const VersionedKeySequence& sequence() const;

    std::vector<ParticipantId> unversioned_sequence() const;

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

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

    bool rejected() const;

    void forfeit(Version version);

    bool forfeited() const;

    bool defunct() const;

    TablePtr respond(ParticipantId by_participant);

    // const-qualified respond()
    ConstTablePtr respond(ParticipantId by_participant) const;

    TablePtr parent();

    // const-qualified parent()
    ConstTablePtr parent() const;

    std::vector<TablePtr> children();

    // const-qualified children()
    std::vector<ConstTablePtr> children() const;

    bool ongoing() const;

    class Implementation;
  private:
    Table();
    rmf_utils::unique_impl_ptr<Implementation> _pimpl;
  };

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

  // const-qualified table()
  ConstTablePtr table(
    ParticipantId for_participant,
    const std::vector<ParticipantId>& to_accommodate) const;

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

  // const-qualified table()
  ConstTablePtr table(const std::vector<ParticipantId>& sequence) const;

  enum class SearchStatus
  {
    Deprecated = 0,

    Absent,

    Found
  };

  template<typename Ptr>
  struct SearchResult
  {
    SearchStatus status;

    Ptr table;

    inline bool deprecated() const
    {
      return SearchStatus::Deprecated == status;
    }

    inline bool absent() const
    {
      return SearchStatus::Absent == status;
    }

    inline bool found() const
    {
      return SearchStatus::Found == status;
    }

    inline operator bool() const
    {
      return found();
    }
  };

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

  SearchResult<ConstTablePtr> find(
    ParticipantId for_participant,
    const VersionedKeySequence& to_accommodate) const;

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

  SearchResult<ConstTablePtr> find(const VersionedKeySequence& sequence) const;

  class Evaluator
  {
  public:

    virtual std::size_t choose(
      const std::vector<const Proposal*>& proposals) const = 0;

    virtual ~Evaluator() = default;
  };

  ConstTablePtr evaluate(const Evaluator& evaluator) const;

  class Implementation;
private:
  Negotiation();
  rmf_utils::unique_impl_ptr<Implementation> _pimpl;
};

//==============================================================================
class QuickestFinishEvaluator : public Negotiation::Evaluator
{
public:

  // Documentation inherited
  std::size_t choose(
    const std::vector<const Negotiation::Proposal*>& proposals) const final;

};

} // namespace schedule
} // namespace rmf_traffic

#endif // RMF_TRAFFIC__SCHEDULE__NEGOTIATION_HPP