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

Related Functions

(Note that these are not member functions.)

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

Member Function Documentation

◆ get_owner_shard()

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

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

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

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

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: