Utility class to store an arbitrary type-erased object while another object is alive. More...

#include <owning_wrapper.hpp>

Public Types
using	deleter_type = void()(void )
	Callback used to delete the owned object.

Public Member Functions
	OwningWrapper (void *obj, deleter_type deleter)
	Take ownership and responsibility for the destruction of an object. More...

void *	release () noexcept
	Release ownership of the underlying pointer. More...

void *	get () const noexcept

Detailed Description

Utility class to store an arbitrary type-erased object while another object is alive.

When sending messages through Channels from Python, we typically need to keep various Python objects alive since the matching C++ objects only hold views.

For example, when constructing a TableChunk from a pylibcudf Table, the TableChunk has a non-owning cudf::table_view of the Table and someone must be responsible for keeping the Table alive for the lifetime of the TableChunk. If we want to allow creation of such objects in Python with the ability to sink them on the C++ side we cannot rely on the Python side of things keeping the Table alive (the reference disappears!). Similarly when we send a message through a Channel the sender will, once pushed into the channel, drop the reference to the message payload and so, again, we need some way of keeping the payload alive.

To square this circle, such C++ objects have an OwningWrapper slot that stores a type-erased pointer with, as far as we are concerned, unique ownership semantics. When this object is destroyed, the custom deleter runs and can do whatever deallocation is necessary.

Warning: Behaviour is undefined if the unique ownership semantic is not respected. The deleter may be called from any thread at any time, the implementer of the deleter is responsible for correct synchronisation with (for example) the Python GIL. Furthermore, the deleter may not throw: if an error occurs, the only safe thing to do is std::terminate.; When using this OwningWrapper inside a C++ object, make sure it is constructed first and destructed last.

Definition at line 42 of file owning_wrapper.hpp.

Constructor & Destructor Documentation

◆ OwningWrapper()

rapidsmpf::OwningWrapper::OwningWrapper	(	void *	obj,
		deleter_type	deleter
	)

inlineexplicit

Take ownership and responsibility for the destruction of an object.

Parameters

obj	Type-erased object to own.
deleter	Function called to destruct the object.

Definition at line 55 of file owning_wrapper.hpp.

Member Function Documentation

◆ get()

void* rapidsmpf::OwningWrapper::get ( ) const

inlinenoexcept

Returns: Get access to the underlying pointer.

Definition at line 70 of file owning_wrapper.hpp.

◆ release()

void* rapidsmpf::OwningWrapper::release ( )

inlinenoexcept

Release ownership of the underlying pointer.

Returns: Pointer to object.

Definition at line 63 of file owning_wrapper.hpp.

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

/__w/rapidsmpf/rapidsmpf/cpp/include/rapidsmpf/owning_wrapper.hpp