Objects Lifetime
Objects lifetime management and ownership.
This is a legacy Apache Ignite documentation
The new documentation is hosted here: https://ignite.apache.org/docs/latest/
Ignite Objects
Apache Ignite objects, such as Ignite or Cache, that are created using Ignite public API are implemented as a thin handler of an internal/underlying object and can be safely and quickly copied or passed to functions by value. It is also a recommended way for passing Ignite objects from one function to another because an underlying object lives as long as there is at least one handler object alive.
// Fast and safe passing of the ignite::Ignite instance to the function.
// Here 'val' points to the same underlying node instance even though
// Ignite object gets copied on call.
// It's guarateed that the underlying object will live as long as 'val'
// object is alive.
void Foo(ignite::Ignite val)
{
...
}
User Objects
Occasionally, your application might need to feed Apache Ignite with a custom object which lifetime can not be easily determined at compile time. For example, when a ContinuousQuery instance is created, you are required to provide the continuous query with an instance of the local listener - CacheEntryEventListener. In such a case, it is unclear whether it is the responsibility of Apache Ignite or the application to manage the local listener's lifetime and release it once it is no longer needed.
Apache Ignite C++ is pretty flexible in this part. It uses ignite::Reference class to address custom objects ownership problem. Refer to the code below to see how this class can be used in practice.
// Ignite function that takes a value of 'SomeType'.
void Foo(ignite::Reference<SomeType> val);
//...
// Defining an object.
SomeType obj1;
// Passing a simple reference to the function.
// Ignite will not get ownership over the instance.
// The application is responsible for keeping instance alive while
// it's used by Ignite and for releasing it once it is no longer needed.
Foo(ignite::MakeReference(obj1);
// Passing the object by copy.
// Ignite gets a copy of the object instance and manages
// its lifetime by itself.
// 'SomeType' is required to have a copy constructor.
foo(ignite::MakeReferenceFromCopy(obj1);
// Defining another object.
SomeType* obj2 = new SomeType;
// Passing object's ownership to the function.
// Ignite will release the object once it's no longer needed.
// The applicaiton must not use the pointer once it have been passed
// to Ignite as it might be released at any point of time.
foo(ignite::MakeReferenceFromOwningPointer(obj2);
std::shared_ptr<SomeType> obj3 = std::make_shared<SomeType>();
// Passing the object by smart pointer.
// In this case, Reference class behaves just like an underlying
// smart pointer type.
foo(ignite::MakeReferenceFromSmartPointer(obj3);
Updated about 5 years ago