Template Class ipc_shared_ptr

Class Documentation

template<typename T>
class ipc_shared_ptr

Smart pointer for zero-copy IPC message sharing between publishers and subscribers.

ipc_shared_ptr manages the lifetime of messages allocated in shared memory. Publishers obtain an instance via Publisher::borrow_loaned_message(), fill in message fields, and transfer ownership with Publisher::publish(). Subscribers receive ipc_shared_ptr<const MessageT> in their callbacks; the kernel-side reference is released when all copies are destroyed.

Thread Safety

Multiple threads can safely hold and destroy different copies of the same pointer (reference counting is atomic). Concurrent access to the same instance requires external synchronization, same as std::shared_ptr.

Invalidation

After publish(), every copy sharing the same control block becomes invalidated:

  • get() returns nullptr, operator bool() returns false.

  • operator->() and operator*() call std::terminate().

Template Parameters:

T – The message type (or const-qualified message type on the subscriber side).

Public Types

using element_type = T

Public Functions

inline const std::string get_topic_name() const
inline topic_local_id_t get_pubsub_id() const
inline int64_t get_entry_id() const
AGNOCAST_PUBLIC ipc_shared_ptr() = default

Construct an empty (null) ipc_shared_ptr.

inline explicit ipc_shared_ptr(T *ptr, const std::string &topic_name, const topic_local_id_t pubsub_id, const int64_t entry_id)
inline ~ipc_shared_ptr()
inline AGNOCAST_PUBLIC ipc_shared_ptr(const ipc_shared_ptr &r)

Copy constructor. Creates a new reference to the same message. The reference count is incremented atomically, so it is safe to copy from an instance that another thread also copies from. However, two threads must not copy-from and write-to the same instance concurrently.

inline AGNOCAST_PUBLIC ipc_shared_ptr & operator= (const ipc_shared_ptr &r)

Copy assignment. Releases the current reference and shares ownership with r. Same thread-safety guarantees as the copy constructor.

Returns:

Reference to *this.

inline AGNOCAST_PUBLIC ipc_shared_ptr(ipc_shared_ptr &&r) noexcept

Move constructor. Transfers ownership from r without changing the reference count. Not thread-safe: the caller must ensure no other thread accesses r concurrently.

inline AGNOCAST_PUBLIC ipc_shared_ptr & operator= (ipc_shared_ptr &&r) noexcept

Move assignment. Releases the current reference and takes ownership from r. Not thread-safe: the caller must ensure no other thread accesses r concurrently.

Returns:

Reference to *this.

template<typename U, typename = std::enable_if_t<std::is_convertible_v<U*, T*>>>
inline AGNOCAST_PUBLIC ipc_shared_ptr(const ipc_shared_ptr<U> &r)

Converting copy constructor (e.g., ipc_shared_ptr<T> to ipc_shared_ptr<const T>). Enabled only when U* is implicitly convertible to T*.

template<typename U, typename = std::enable_if_t<std::is_convertible_v<U*, T*>>>
inline AGNOCAST_PUBLIC ipc_shared_ptr(ipc_shared_ptr<U> &&r)

Converting move constructor (e.g., ipc_shared_ptr<T> to ipc_shared_ptr<const T>). Enabled only when U* is implicitly convertible to T*.

template<typename U, typename = std::enable_if_t<std::is_convertible_v<U *, T *>>> inline AGNOCAST_PUBLIC ipc_shared_ptr & operator= (const ipc_shared_ptr< U > &r)

Converting copy assignment (e.g., ipc_shared_ptr<T> to ipc_shared_ptr<const T>). Enabled only when U* is implicitly convertible to T*.

Returns:

Reference to *this.

template<typename U, typename = std::enable_if_t<std::is_convertible_v<U *, T *>>> inline AGNOCAST_PUBLIC ipc_shared_ptr & operator= (ipc_shared_ptr< U > &&r)

Converting move assignment (e.g., ipc_shared_ptr<T> to ipc_shared_ptr<const T>). Enabled only when U* is implicitly convertible to T*.

Returns:

Reference to *this.

template<typename U>
inline ipc_shared_ptr(const ipc_shared_ptr<U> &r, T *ptr) noexcept
template<typename U>
inline ipc_shared_ptr(ipc_shared_ptr<U> &&r, T *ptr) noexcept
inline AGNOCAST_PUBLIC T & operator* () const noexcept

Dereference the managed message. Calls std::terminate() if the pointer has been invalidated by publish().

Returns:

Reference to the managed message.

inline AGNOCAST_PUBLIC T * operator-> () const noexcept

Access a member of the managed message. Calls std::terminate() if the pointer has been invalidated by publish().

Returns:

Pointer to the managed message.

inline AGNOCAST_PUBLIC operator bool() const noexcept

Return true if the pointer is non-null and has not been invalidated.

Returns:

True if non-null and not invalidated.

inline AGNOCAST_PUBLIC T * get () const noexcept

Return the raw pointer, or nullptr if empty or invalidated.

Returns:

Raw pointer, or nullptr if empty or invalidated.

inline AGNOCAST_PUBLIC void reset ()

Release ownership of the managed message. If this is the last reference: on the subscriber side, notifies the kernel module that the message can be reclaimed; on the publisher side (if unpublished), frees the allocated memory.