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 any pointer type – raw pointer, 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_ptr >	copy () 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_ptr &	operator= (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 ( )

inlinenoexcept

Destroy the managed pointer.

Returns

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

inlinenoexcept

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 ( )

inlinenoexcept

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 )

inlinenoexcept

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 )

inlinenoexcept

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:

• seastar/core/sharded.hh