Qore Programming Language - C/C++ Library 2.0.0
Loading...
Searching...
No Matches
QoreTypeSafeReferenceHelper Class Reference

helper class to manage variable references passed to functions and class methods, stack only, cannot be dynamically allocated More...

#include <QoreTypeSafeReferenceHelper.h>

Public Member Functions

DLLEXPORT QoreTypeSafeReferenceHelper (const ReferenceNode *ref, ExceptionSink *xsink)
 initializes the object and tries to get the pointer to the pointer of the lvalue expression target
 
DLLEXPORT QoreTypeSafeReferenceHelper (ExceptionSink *xsink)
 Initializes the object without a reference.
 
DLLEXPORT ~QoreTypeSafeReferenceHelper ()
 destroys the object
 
DLLEXPORT int assign (QoreValue val)
 assigns a value to the reference, assumes the reference is valid
 
DLLEXPORT void close ()
 Closes the object and unlocks all locks.
 
DLLEXPORT ExceptionSinkgetExceptionSink () const
 Returns the ExceptionSink object.
 
DLLEXPORT const QoreTypeInfo * getReferenceTypeInfo () const
 Returns the type of the reference.
 
DLLEXPORT qore_type_t getType () const
 returns the type of the reference's value
 
DLLEXPORT const char * getTypeName () const
 returns the type name of the reference's value
 
DLLEXPORT AbstractQoreNodegetUnique ()
 returns a pointer to the value with a unique reference count (so it can be updated in place)
 
template<typename T >
DLLLOCAL T * getUnique ()
 returns a pointer to the value with a unique reference count (so it can be updated in place)
 
DLLEXPORT const QoreValue getValue () const
 returns the reference's value
 
DLLEXPORT AutoVLockgetVLock () const
 Returns the variable lock.
 
DLLEXPORT bool isLocked () const
 Returns true if managing a lock.
 
DLLEXPORT int moveToHashObjKey (const char *key, bool for_remove=false)
 Moves the reference to the given key of the hash or object of the current value.
 
DLLEXPORT operator bool () const
 returns true if the reference is valid, false if not
 
DLLEXPORT QoreValue removeHashObjKey (const char *key)
 Removes the given key of the current hash or object.
 
DLLEXPORT int reset (const ReferenceNode *ref, ExceptionSink *xsink)
 Clears any existing reference and assigns the reference to use.
 
DLLEXPORT int set (const ReferenceNode *ref)
 Assigns the reference to use.
 
DLLEXPORT int setObjKey (QoreObject *obj, const char *key, bool for_remove=false)
 Moves the reference to the given key of the given object.
 

Detailed Description

helper class to manage variable references passed to functions and class methods, stack only, cannot be dynamically allocated

Takes care of safely accessing ReferenceNode objects, for example when they are passed as arguments to a builtin function or method. Locks are automatically acquired in the constructor if necessary and released in the destructor. The constructor could raise a Qore-language exception if there is a deadlock acquiring any locks to access the ReferenceNode's value as given by the lvalue expression, so the object should be checked for this state right after the constructor as in the following example:

if (p.getType() == NT_REFERENCE) {
const ReferenceNode *r = p.get<const ReferenceNode>();
// a deadlock exception occurred accessing the reference's value pointer
if (!ref)
return QoreValue();
// more code to access the reference
}
DLLLOCAL detail::QoreValueCastHelper< T >::Result get()
returns the value as the given type
Definition QoreValue.h:214
DLLEXPORT qore_type_t getType() const
returns the type of value contained
helper class to manage variable references passed to functions and class methods, stack only,...
Definition QoreTypeSafeReferenceHelper.h:57
parse type: reference to a lvalue expression
Definition ReferenceNode.h:45
const qore_type_t NT_REFERENCE
type value for ReferenceNode
Definition node_types.h:64
static QoreValue get_param_value(const QoreListNode *n, size_t i)
returns the argument in the position given or 0 if there is none
Definition params.h:78
The main value class in Qore, designed to be passed by value.
Definition QoreValue.h:279

Constructor & Destructor Documentation

◆ QoreTypeSafeReferenceHelper() [1/2]

DLLEXPORT QoreTypeSafeReferenceHelper::QoreTypeSafeReferenceHelper ( ExceptionSink * xsink)

Initializes the object without a reference.

After this, use set(const ReferenceNode* ref)

◆ QoreTypeSafeReferenceHelper() [2/2]

DLLEXPORT QoreTypeSafeReferenceHelper::QoreTypeSafeReferenceHelper ( const ReferenceNode * ref,
ExceptionSink * xsink )

initializes the object and tries to get the pointer to the pointer of the lvalue expression target

Parameters
refthe ReferenceNode to use
xsinkQore-language exceptions raised will be added here (for example, a deadlock accessing the object)

Member Function Documentation

◆ assign()

DLLEXPORT int QoreTypeSafeReferenceHelper::assign ( QoreValue val)

assigns a value to the reference, assumes the reference is valid

Parameters
valthe value to assign (must be already referenced for the assignment)
Returns
0 if there was no error and the variable was assigned, -1 if a Qore-language exception occured dereferencing the current value, in this case no assignment was made and the reference count for val is dereferenced automatically by the QoreTypeSafeReferenceHelper object
Note
you must check that the reference is valid before calling this function
// if the reference is not valid, then return
if (!rh)
return;
// make the assignment (if the assignment fails, the value will be dereferenced automatically)
rh.assign(val->refSelf());

◆ close()

DLLEXPORT void QoreTypeSafeReferenceHelper::close ( )

Closes the object and unlocks all locks.

After this call, the object cannot be used

◆ getType()

DLLEXPORT qore_type_t QoreTypeSafeReferenceHelper::getType ( ) const

returns the type of the reference's value

Returns
the type of the reference's value

◆ getTypeName()

DLLEXPORT const char * QoreTypeSafeReferenceHelper::getTypeName ( ) const

returns the type name of the reference's value

Returns
the type name of the reference's value

◆ getUnique() [1/2]

DLLEXPORT AbstractQoreNode * QoreTypeSafeReferenceHelper::getUnique ( )

returns a pointer to the value with a unique reference count (so it can be updated in place)

assumes the reference is valid and the lvalue holds a reference-counted AbstractQoreNode*, if not, this call will cause a segfault

Returns
a pointer to the reference's value with a unique reference count (so it can be modified), or 0 if the value was 0 to start with or if a Qore-language exception was raised
Note
you must check that the reference is valid before calling this function
take care to only call this function on types where the AbstractQoreNode::realCopy() function has a valid implementation (on all value types suitable for in-place modification this function has a valid implementation), as in debugging builds other types will abort(); in non-debugging builds this function will cause a segfault
// if the reference is not valid, then return
if (!rh)
return;
if (rh.getType() == NT_LIST) {
// get the unique value
QoreListNode* l = static_cast<QoreListNode*>(rh.getUnique(xsink));
// if a Qore-language exception was raised, then return
if (*xsink)
return;
}
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition QoreListNode.h:52
const qore_type_t NT_LIST
type value for QoreListNode
Definition node_types.h:50

Referenced by getUnique().

◆ getUnique() [2/2]

template<typename T >
DLLLOCAL T * QoreTypeSafeReferenceHelper::getUnique ( )
inline

returns a pointer to the value with a unique reference count (so it can be updated in place)

assumes the reference is valid and the lvalue holds a reference-counted AbstractQoreNode*, if not, this call will cause a segfault

Returns
a pointer to the reference's value with a unique reference count (so it can be modified), or 0 if the value was 0 to start with or if a Qore-language exception was raised
Note
you must check that the reference is valid before calling this function
take care to only call this function on types where the AbstractQoreNode::realCopy() function has a valid implementation (on all value types suitable for in-place modification this function has a valid implementation), as in debugging builds other types will abort(); in non-debugging builds this function will cause a segfault
// if the reference is not valid, then return
if (!rh)
return;
if (rh.getType() == NT_LIST) {
// get the unique value
QoreListNode* l = static_cast<QoreListNode*>(rh.getUnique(xsink));
// if a Qore-language exception was raised, then return
if (*xsink)
return;
}

References getUnique().

◆ getValue()

DLLEXPORT const QoreValue QoreTypeSafeReferenceHelper::getValue ( ) const

returns the reference's value

Returns
the value of the lvalue reference

◆ operator bool()

DLLEXPORT QoreTypeSafeReferenceHelper::operator bool ( ) const

returns true if the reference is valid, false if not

false will only be returned if a Qore-language exception was raised in the constructor

◆ reset()

DLLEXPORT int QoreTypeSafeReferenceHelper::reset ( const ReferenceNode * ref,
ExceptionSink * xsink )

Clears any existing reference and assigns the reference to use.

Returns
-1 for error (Qore-language exception raised), or 0 for success

◆ set()

DLLEXPORT int QoreTypeSafeReferenceHelper::set ( const ReferenceNode * ref)

Assigns the reference to use.

Only to be used after QoreTypeSafeReferenceHelper(ExceptionSink* xsink)


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