High performance C++ framework for concurrent servers
Public Types | Public Member Functions | Related Functions | List of all members
seastar::foreign_ptr< PtrType > Class Template Reference

Detailed Description

template<typename PtrType>
class seastar::foreign_ptr< PtrType >

Smart pointer wrapper which makes it safe to move across CPUs.

foreign_ptr<> is a smart pointer wrapper which, unlike shared_ptr and lw_shared_ptr, is safe to move to a different core.

As seastar avoids locking, any but the most trivial objects must be destroyed on the same core they were created on, so that, for example, their destructors can unlink references to the object from various containers. In addition, for performance reasons, the shared pointer types do not use atomic operations to manage their reference counts. As a result they cannot be used on multiple cores in parallel.

foreign_ptr<> provides a solution to that problem. foreign_ptr<> wraps smart pointers – seastar::shared_ptr<>, or similar, and remembers on what core this happened. When the foreign_ptr<> object is destroyed, it sends a message to the original core so that the wrapped object can be safely destroyed.

foreign_ptr<> is a move-only object; it cannot be copied.

#include <seastar/core/sharded.hh>

Public Types

using element_type = typename std::pointer_traits< PtrType >::element_type
using pointer = element_type *

Public Member Functions

 foreign_ptr () noexcept(std::is_nothrow_default_constructible_v< PtrType >)
 Constructs a null foreign_ptr<>.
 foreign_ptr (std::nullptr_t) noexcept(std::is_nothrow_default_constructible_v< foreign_ptr >)
 Constructs a null foreign_ptr<>.
 foreign_ptr (PtrType value) noexcept(std::is_nothrow_move_constructible_v< PtrType >)
 Wraps a pointer object and remembers the current core.
 foreign_ptr (const foreign_ptr &)=delete
 foreign_ptr (foreign_ptr &&other) noexcept(std::is_nothrow_move_constructible_v< PtrType >)=default
 Moves a foreign_ptr<> to another object.
 ~foreign_ptr ()
 Destroys the wrapped object on its original cpu.
future< foreign_ptrcopy () const noexcept
 Creates a copy of this foreign ptr. Only works if the stored ptr is copyable.
element_type & operator* () const noexcept(noexcept(*_value))
 Accesses the wrapped object.
element_type * operator-> () const noexcept(noexcept(&*_value))
 Accesses the wrapped object.
pointer get () const noexcept(noexcept(&*_value))
 Access the raw pointer to the wrapped object.
unsigned get_owner_shard () const noexcept
 operator bool () const noexcept(noexcept(static_cast< bool >(_value)))
 Checks whether the wrapped pointer is non-null.
foreign_ptroperator= (foreign_ptr &&other) noexcept(std::is_nothrow_move_constructible< PtrType >::value)
 Move-assigns a foreign_ptr<>.
PtrType release () noexcept(std::is_nothrow_default_constructible_v< PtrType >)
void reset (PtrType new_ptr) noexcept(std::is_nothrow_move_constructible_v< PtrType >)
void reset (std::nullptr_t=nullptr) noexcept(std::is_nothrow_default_constructible_v< PtrType >)
future destroy () noexcept

Related Functions

(Note that these are not member functions.)

template<typename T >
foreign_ptr< T > make_foreign (T ptr)

Member Function Documentation

◆ destroy()

template<typename PtrType >
future seastar::foreign_ptr< PtrType >::destroy ( )

Destroy the managed pointer.

a future that is resolved when managed pointer is destroyed on its owner shard.

◆ get_owner_shard()

template<typename PtrType >
unsigned seastar::foreign_ptr< PtrType >::get_owner_shard ( ) const

Return the owner-shard of this pointer.

The owner shard of the pointer can change as a result of move-assigment or a call to reset().

◆ release()

template<typename PtrType >
PtrType seastar::foreign_ptr< PtrType >::release ( )

Releases the owned pointer

Warning: the caller is now responsible for destroying the pointer on its owner shard. This method is best called on the owner shard to avoid accidents.

◆ reset() [1/2]

template<typename PtrType >
void seastar::foreign_ptr< PtrType >::reset ( PtrType  new_ptr)

Replace the managed pointer with new_ptr.

The previous managed pointer is destroyed on its owner shard.

◆ reset() [2/2]

template<typename PtrType >
void seastar::foreign_ptr< PtrType >::reset ( std::nullptr_t  = nullptr)

Replace the managed pointer with a null value.

The previous managed pointer is destroyed on its owner shard.

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