GazeTargetWaiter.h

Go to the documentation of this file.

#pragma once
 
#include <condition_variable>
#include <functional>
#include <map>
#include <mutex>
#include <optional>
#include <string>
 
#include <ArmarXCore/core/time/Duration.h>
 
#include <RobotAPI/libraries/armem/core/MemoryID.h>
 
#include <armarx/view_selection/gaze_targets/GazeTargetStatus.h>
 
namespace armarx::view_selection::client
{
    class StatusHandlerInterface;
 
    /**
     * @brief Blocks until the gaze is fixed on a requested target.
     *
     * The analogue of navigation's client::Navigator::waitForStop, with two differences that matter
     * here:
     *
     * - An expectation is armed *before* the target is committed, so a status that arrives while
     *   the caller is still on its way into wait() is not lost.  (navigation::client::Navigator
     *   documents this as an open race.)
     * - Waiting sleeps on a condition variable rather than spinning on a future, and re-checks the
     *   abort predicate on a fixed tick.
     *
     * One instance serves a whole client: expectations are keyed by target name, which is also the
     * memory entity name, so concurrently running skills necessarily use distinct keys.
     */
    class GazeTargetWaiter
    {
    public:
        struct Result
        {
            gaze_targets::GazeTargetStatus status;
 
            /// Why the wait ended, if it did not end on a status update.
            std::string message;
 
            /**
             * @brief Whether the gaze was fixed on the target at some point.
             *
             * Not `status == Reached`: a target that was reached and then superseded reports
             * Released, and a client that only observes that last snapshot must still count its
             * request as fulfilled.  The scheduler accumulates the timestamps precisely so this
             * single test is sufficient.
             */
            explicit operator bool() const;
        };
 
        explicit GazeTargetWaiter(StatusHandlerInterface& handler);
 
        /// Start collecting updates for this target.  Call before committing it.
        void expect(const std::string& targetName);
 
        /// Narrow the expectation to the exact request snapshot, once the commit returned its ID.
        void bind(const std::string& targetName, const armem::MemoryID& gazeTargetID);
 
        /// Drop an expectation without waiting for it.
        void forget(const std::string& targetName);
 
        /**
         * @brief Block until the target is reached, ends, the abort predicate fires or the timeout
         * expires.  Consumes the expectation.
         *
         * @param timeout      A non-positive duration waits indefinitely.
         * @param shouldAbort  Polled regularly; typically the skill's shouldSkillTerminate().
         */
        Result wait(const std::string& targetName,
                    const armarx::Duration& timeout,
                    const std::function<bool()>& shouldAbort);
 
    private:
        struct Expectation
        {
            /// Set once the commit's snapshot ID is known; until then updates match by name alone.
            std::optional<armem::MemoryID> gazeTargetID;
 
            /// Most recent matching update.
            gaze_targets::GazeTargetStatus status;
 
            /// Whether the outcome is decided: reached, or terminal.
            bool settled = false;
        };
 
        void handleStatus(const gaze_targets::GazeTargetStatus& status);
 
        std::mutex mutex;
 
        std::condition_variable condition;
 
        std::map<std::string, Expectation> expectations;
    };
 
} // namespace armarx::view_selection::client