Wt::Dbo::ptr< C > Class Template Reference

A smart pointer for a database object. More...

#include <Wt/Dbo/ptr.h>

Inherits Wt::Dbo::ptr_base.

Public Member Functions
	ptr (std::unique_ptr< C > obj)
	Creates a new pointer. More...
	ptr (const ptr< C > &other)
	Copy constructor.
	ptr (ptr< C > &&other) noexcept
	Move constructor.
virtual	~ptr ()
	Destructor. More...
void	reset (std::unique_ptr< C > obj=nullptr)
	Resets the pointer. More...
ptr< C > &	operator= (const ptr< C > &other)
	Copy assignment operator.
ptr< C > &	operator= (ptr< C > &&other) noexcept
	Move assignment operator.
const C *	operator-> () const
	Dereference operator. More...
const C *	get () const
	Returns the pointer. More...
const C &	operator* () const
	Dereference operator. More...
C *	modify () const
	Dereference operator, for writing. More...
bool	operator== (const ptr< C > &other) const
	Comparison operator. More...
bool	operator== (const weak_ptr< C > &other) const
	Comparison operator. More...
bool	operator!= (const ptr< C > &other) const
	Comparison operator. More...
bool	operator!= (const weak_ptr< C > &other) const
	Comparison operator. More...
bool	operator< (const ptr< C > &other) const
	Comparison operator. More...
	operator bool () const
	Checks for null. More...
void	flush () const
	Flushes the object. More...
void	remove ()
	Removes an object from the database. More...
void	reread ()
	Rereads the database version. More...
void	purge ()
	Purges an object from memory. More...
dbo_traits< C >::IdType	id () const
	Returns the object id. More...
int	version () const
	Returns the object version. More...
bool	isTransient () const
	Returns whether the object is transient. More...
bool	isDirty () const
	Returns whether the object is dirty. More...
Session *	session () const
	Returns the session with which this pointer is associated. More...

Detailed Description

template<class C>
class Wt::Dbo::ptr< C >

A smart pointer for a database object.

This smart pointer class implements a reference counted shared pointer for database objects, which also keeps tracking of synchronization between the in-memory copy and the database copy. You should always use this pointer class to reference a database object.

Unlike typical C++ data structures, classes mapped to database tables do not have clear ownership relationships. Therefore, the conventional ownership-based memory allocation/deallocation does not work naturally for database classes.

A pointer may point to a transient object or a persisted object. A persisted object has a corresponding copy in the database while a transient object is only present in memory. To persist a new object, use Session::add(). To make a persisted object transient, use remove().

Unlike a typical smart pointer, this pointer only allows read access to the underlying object by default. To modify the object, you should explicitly use modify(). This is used to mark the underyling object as dirty to add it to the queue of objects to be synchronized with the database.

The pointer class provides a number of methods to deal with the persistence state of the object:

• id(): returns the database id
• flush(): forces the object to be synchronized to the database
• remove(): deletes the object in the underlying database
• reread(): rereads the database copy of the object
• purge(): purges the transient version of a non-dirty object.

Wt::Dbo::ptr<const C> can be used when retrieving query results. There are overloads for the copy constructor, copy assignment, and comparison operators to make this work as expected.

Constructor & Destructor Documentation

ptr()

template<class C >

Wt::Dbo::ptr< C >::ptr

(

std::unique_ptr< C >

obj

)

Creates a new pointer.

When obj is not nullptr, the pointer points to the new unpersisted object. Use Session::add() to persist the newly created object.

~ptr()

template<class C >

Wt::Dbo::ptr< C >::~ptr

virtual

Destructor.

This method will delete the transient copy of the database object if it is not referenced by any other pointer.

Member Function Documentation

flush()

template<class C >

void Wt::Dbo::ptr< C >::flush

Flushes the object.

If dirty, the object is synchronized to the database. This will automatically also flush objects that are referenced by this object if needed. The object is not actually committed to the database before the active transaction has been committed.

Since this may persist object to the database, you should have an active transaction.

get()

template<class C >

const C * Wt::Dbo::ptr< C >::get

Returns the pointer.

Note that returns a const pointer. Use modify() to get a non-const pointer.

Since this may lazy-load the underlying database object, you should have an active transaction.

See also

modify()

id()

template<class C >

dbo_traits< C >::IdType Wt::Dbo::ptr< C >::id

Returns the object id.

This returns dbo_traits<C>::invalidId() for a transient object.

isDirty()

template<class C >

bool Wt::Dbo::ptr< C >::isDirty

Returns whether the object is dirty.

A dirty object will be flushed whenever a query is made or the current transaction ends.

isTransient()

template<class C >

bool Wt::Dbo::ptr< C >::isTransient

Returns whether the object is transient.

This returns true for a transient object.

modify()

template<class C >

ptr< C >::mutator Wt::Dbo::ptr< C >::modify

Dereference operator, for writing.

Returns the underlying object (or, rather, a proxy for it) with the intention to modify it. The proxy object will mark the object as dirty from its destructor. An involved modification should therefore preferably be implemented as a separate method or function to make sure that the object is marked as dirty after the whole modification:

ptr<A> a = ...;
a.modify()->doSomething();

Since this may lazy-load the underlying database object, you should have an active transaction.

See also

get()

operator bool()

template<class C >

Wt::Dbo::ptr< C >::operator bool

explicit

Checks for null.

Returns true if the pointer is pointing to a non-null object.

operator!=() [1/2]

template<class C >

bool Wt::Dbo::ptr< C >::operator!=

(

const ptr< C > &

other

)

const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

operator!=() [2/2]

template<class C >

bool Wt::Dbo::ptr< C >::operator!=

(

const weak_ptr< C > &

other

)

const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

Since this needs to query the value, you should have an active transaction.

operator*()

template<class C >

const C & Wt::Dbo::ptr< C >::operator*

Dereference operator.

Note that this operator returns a const copy of the referenced object. Use modify() to get a non-const reference.

Since this may lazy-load the underlying database object, you should have an active transaction.

operator->()

template<class C >

const C * Wt::Dbo::ptr< C >::operator->

Dereference operator.

Note that this operator returns a const copy of the referenced object. Use modify() to get a non-const reference.

Since this may lazy-load the underlying database object, you should have an active transaction.

operator<()

template<class C >

bool Wt::Dbo::ptr< C >::operator<

(

const ptr< C > &

other

)

const

Comparison operator.

This operator is implemented to be able to store pointers in std::set or std::map containers.

operator==() [1/2]

template<class C >

bool Wt::Dbo::ptr< C >::operator==

(

const ptr< C > &

other

)

const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

operator==() [2/2]

template<class C >

bool Wt::Dbo::ptr< C >::operator==

(

const weak_ptr< C > &

other

)

const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

Since this needs to query the value, you should have an active transaction.

purge()

template<class C >

void Wt::Dbo::ptr< C >::purge

Purges an object from memory.

When the object is not dirty, the memory copy of the object is deleted, and the object will be reread from the database on the next access.

Purging an object can be useful to conserve memory, but you should never purge an object while the user is editing if you wish to rely on the optimistick locking for detecting concurrent modifications.

remove()

template<class C >

void Wt::Dbo::ptr< C >::remove

Removes an object from the database.

The object is removed from the database, and becomes transient again.

Note that the object is not deleted in memory: you can still continue to read and modify the object, but there will no longer be a database copy of the object, and the object will effectively be treated as a new object (which may be re-added to the database at a later point).

This is the opposite operation of Session::add().

reread()

template<class C >

void Wt::Dbo::ptr< C >::reread

Rereads the database version.

Rereads a persisted object from the database, discarding any possible changes and updating to the latest database version.

This does not actually load the database version, since loading is lazy.

reset()

template<class C >

void Wt::Dbo::ptr< C >::reset

(

std::unique_ptr< C >

obj = nullptr< C >

)

Resets the pointer.

This is equivalent to:

p = ptr<C>(std::move(obj));

session()

template<class C >

Session * Wt::Dbo::ptr< C >::session

Returns the session with which this pointer is associated.

This may return nullptr if the pointer is null or not added to a session.

version()

template<class C >

int Wt::Dbo::ptr< C >::version

Returns the object version.

This returns -1 for a transient object or when versioning is not enabled.