rclcpp::Future< T, Cap > Class Template Reference

#include <future.hpp>

Public Member Functions
void	cancel ()
	Future ()
	Default constructor – creates an empty/consumed future.
	Future (Future &&other) noexcept
template<typename U = void>
void	get ()
bool	is_consumed () const
	Check if the future has been consumed or cancelled.
bool	is_ready ()
Future &	operator= (Future &&other) noexcept
Result	try_take (T &out)
bool	valid () const
Result	wait (void *executor_handle, uint32_t timeout_ms, T &out, uint32_t poll_ms=10)
	~Future ()

Friends
template<typename S>
class	::rclcpp::PollClient
template<typename A>
class	::rclcpp_action::Client

Detailed Description

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>
class rclcpp::Future< T, Cap >

Single-shot deferred result for request/response operations.

Returned by PollClient<S>::send_request (phase-456 W9; it was Client<S>::send_request before the split). The future is consumed when the result is taken – move-only, single-shot.

Usage:

auto fut = client.send_request(req);
ResponseType resp;
RCLCPP_TRY(fut.wait(executor.handle(), 5000, resp));

Template Parameters

Cap

Bytes the RECEIVE buffer holds. Defaults to T's own derived bound where it has one, and to the legacy T::SERIALIZED_SIZE_MAX estimate where it does not. The _sized escape hatches are Client::send_request_sized and ActionClient::get_result_future_sized, which hand back a Future<T, N> (issue 0964). This buffer IS the capacity: under-sizing it truncates the reply.

A service future is KEYED BY ITS REQUEST'S SEQUENCE ID (issue 2009): any number of futures may be in flight on one PollClient, each receives only the reply to its own request whichever future happens to poll first, and a reply that arrives after the future was cancelled, removed (remove_pending_request) or destroyed is dropped — never handed to a later future. See detail::PendingList for the bound and for backends that cannot assign ids.

An ACTION future (rclcpp_action::Client<A>::send_goal_future / get_result_future) is KEYED BY ITS GOAL the same way (issue 2011): it is on its client's list of acceptances or of results, it receives only its own goal's, and a reply for a goal nobody waits on — or arriving after the future was cancelled or destroyed — is dropped. Two action clients keep two sets of lists, so they never see each other's replies.

Constructor & Destructor Documentation

Future() [1/2]

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

rclcpp::Future< T, Cap >::Future ( Future< T, Cap > && other )

inlinenoexcept

~Future()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

rclcpp::Future< T, Cap >::~Future ( )

inline

Future() [2/2]

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

rclcpp::Future< T, Cap >::Future ( )

inline

Default constructor – creates an empty/consumed future.

Member Function Documentation

cancel()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

void rclcpp::Future< T, Cap >::cancel ( )

inline

Cancel the pending operation (idempotent). A service future leaves its client's pending list, so its reply — if it still comes — is dropped (issue 2009).

get()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

template<typename U = void>

void rclcpp::Future< T, Cap >::get ( )

inline

Freestanding: get() is REFUSED at compile time — no <memory>, no allocator. The message names try_take and wait (issue 1996).

is_consumed()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

bool rclcpp::Future< T, Cap >::is_consumed ( ) const

inline

Check if the future has been consumed or cancelled.

is_ready()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

bool rclcpp::Future< T, Cap >::is_ready ( )

inline

Check if the result has arrived (non-blocking).

For a service future this takes replies off the client until its own arrives: one for another pending future is handed to that future, one for no pending future is dropped (at most detail::MAX_STALE_DRAIN_PER_POLL per call).

operator=()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

Future & rclcpp::Future< T, Cap >::operator= ( Future< T, Cap > && other )

inlinenoexcept

try_take()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

Result rclcpp::Future< T, Cap >::try_take ( T & out )

inline

Take the result if ready, consuming the future.

Parameters

out	Output object (filled on success).

Returns

Result::success() on ready, ErrorCode::Error if not ready or failed.

valid()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

bool rclcpp::Future< T, Cap >::valid ( ) const

inline

std::future::valid() — true until the result is taken or the future is cancelled (issue 1996). The negation of is_consumed.

Issue 2009 — also false once the client it was sent on was destroyed (or moved over) while the request was pending.

wait()

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

Result rclcpp::Future< T, Cap >::wait ( void * executor_handle, uint32_t timeout_ms, T & out, uint32_t poll_ms = 10 )

inline

Block until the result arrives, spinning the executor.

Parameters

executor_handle	Raw executor handle (Executor::handle() or global).
timeout_ms	Maximum wait time in milliseconds.
out	Output object (filled on success).
poll_ms	Per-iteration spin_once timeout in ms (default 10). Smaller values give lower latency when the reply arrives mid-step but wake the executor more often; larger values reduce wakeups for long waits.

Returns

Result::success(), ErrorCode::Timeout, or error.

Friends And Related Symbol Documentation

::rclcpp::PollClient

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

template<typename S>

friend class ::rclcpp::PollClient

friend

::rclcpp_action::Client

template<typename T, size_t Cap = ::rclcpp::rx_buffer_capacity<T>::value>

template<typename A>

friend class ::rclcpp_action::Client

friend

---

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

• include/rclcpp/future.hpp