Rose::BinaryAnalysis::InstructionPtr Class Reference

Description

Pointer to an instruction.

Since instruction ASTs are easily recomputed from the bytes that form the instruction, it should be possible to delete such ASTs and reconstruct them on demand (when the smart pointer is dereferenced), thus implementing a form of instruction caching. Unfortunately, ROSE doesn't have clear rules about who owns each node of an AST, and that makes it impossible to implement AST deletion in a safe manner (which is why most analysis authors never delete any AST nodes).

This class and the associated rules and exceptions (below) attempt to rectify this situation as much as possible for the limited case of instruction ASTs. Instruction ASTs fall into two categories: (1) those ASTs that are managed through these smart pointers, known as "managed ASTs", and (2) those ASTs that are not managed through these smart pointers, known as "unmanaged ASTs". A managed AST can be pointed to (at the root or any descendent node) in one of these ways:

• The root of a managed AST can be pointed to by any number of smart pointers. The smart pointers implement a form of shared ownership.

• Any node of a managed AST can be pointed to by a raw pointer provided that there exists at least one smart pointer pointing to the root of that AST and at least one of those smart pointers is in a locked state (see below).

• The nodes of managed AST can have raw pointers to their immediate children, and each child can each have a raw pointer to its immediate parent.

Locking an AST prevents it from being deleted, such as preventing it from being evicted from an instruction cache by some other thread. All locks are applied to the root of the AST, which in turn affects the whole AST. Locks are recursive: an AST can be locked numerous times and will become unlocked only when all locks are relinguished. The two types are locks are RAII locks and temporary locks. Both types get unlocked automatically and are exception safe.

RAII locks are an explicit form of locking an AST and are implemented by the InstructionGuard type. This class has a constructor that takes a smart pointer argument. The lock is held until the guard variable is deleted, such as when it goes out of scope.

// Example of an RAII lock
InstructionPtr insn = ...; // some instruction AST
{
    InstructionGuard lock(insn); // the instruction is now locked
    ::traverse(::preorder, insn.raw()); // this SageIII function is safe to call
} // the instruction is now unlocked (if this was the only lock)

The other type of locks, temporary locks, are fully automatic in that they get created and destroyed implicitly, but they last only for the duration of a C++ expression.

// Example of a temporary lock
InstructionPtr insn = ...; // some instruction AST
std::cout <<insn->get_operandsList()->get_operands().size(); // lock is held for lifetime of expression

Here are some implementation details that might clear things up... An InstructionPtr is basically like an std::shared_ptr except it has no operator* since it cannot be made safe in this situation, and its arrowoperator" returns a different type. The C++ arrow operator is recursive in nature, and we use that to our benefit. The InstructionPtr arrow operator returns a reference to a ManagedInstruction object (which is stored in the InstructionCache). The ManagedInstruction arrow operator ensures that the AST exists, recreating it if necessary, and returns a new LockedInstruction object. The LockedInstruction arrow operator finally returns a SgAsmInstruction pointer.

Thread safety: The smart pointers themselves and the associated locks are thread safe. The objects to which they point and the AST as a whole is generally not thread safe. Note that this is more strict than what the standard requires for std::shared_ptr.

Definition at line 273 of file InstructionCache.h.

#include <Rose/BinaryAnalysis/InstructionCache.h>

Public Member Functions
	InstructionPtr ()
	Construct a null pointer.
	InstructionPtr (const InstructionPtr &other)
	Copy constructor.
InstructionPtr &	operator= (const InstructionPtr &other)
	Assignment operator.
void	reset ()
	Clear the pointer.
SgAsmInstruction &	operator* () const =delete
LockedInstruction	operator-> () const
	Dereference.
	operator bool () const
	Test whether pointer is non-null.
LockedInstruction	lock () const
	Return a locking pointer.
SgAsmInstruction *	take ()
	Give ownership to caller.
bool	operator== (const InstructionPtr &other) const
	Comparison.
bool	operator!= (const InstructionPtr &other) const
	Comparison.
bool	operator<= (const InstructionPtr &other) const
	Comparison.
bool	operator>= (const InstructionPtr &other) const
	Comparison.
bool	operator< (const InstructionPtr &other) const
	Comparison.
bool	operator> (const InstructionPtr &other) const
	Comparison.
bool	operator== (std::nullptr_t) const
	Comparison.
bool	operator!= (std::nullptr_t) const
	Comparison.

Constructor & Destructor Documentation

InstructionPtr() [1/2]

Rose::BinaryAnalysis::InstructionPtr::InstructionPtr ( )

inline

Construct a null pointer.

Definition at line 279 of file InstructionCache.h.

InstructionPtr() [2/2]

Rose::BinaryAnalysis::InstructionPtr::InstructionPtr ( const InstructionPtr &  other )

inline

Copy constructor.

Definition at line 282 of file InstructionCache.h.

Member Function Documentation

operator=()

InstructionPtr & Rose::BinaryAnalysis::InstructionPtr::operator= ( const InstructionPtr &  other )

inline

Assignment operator.

Thread safety: This function is thread safe.

Definition at line 457 of file InstructionCache.h.

References lock().

reset()

void Rose::BinaryAnalysis::InstructionPtr::reset

(

)

Clear the pointer.

Sets the pointer back to being a null pointer.

Thread safety: This function is thread safe.

operator->()

LockedInstruction Rose::BinaryAnalysis::InstructionPtr::operator-> ( ) const

inline

Dereference.

Dereference this pointer to obtain a locked pointer.

Thread safety: This function is thread safe.

Definition at line 464 of file InstructionCache.h.

References lock().

operator bool()

Rose::BinaryAnalysis::InstructionPtr::operator bool ( ) const

inlineexplicit

Test whether pointer is non-null.

Returns true if non-null, false if null.

Thread safety: This function is thread safe.

Definition at line 508 of file InstructionCache.h.

lock()

LockedInstruction Rose::BinaryAnalysis::InstructionPtr::lock

(

)

const

Return a locking pointer.

Returns a pointer that causes the underlying instruction AST to be locked in memory for at least the lifetime of the returned pointer.

Referenced by operator!=(), operator->(), and operator=().

take()

SgAsmInstruction * Rose::BinaryAnalysis::InstructionPtr::take

(

)

Give ownership to caller.

The AST and its ownership is transferred to the caller. This operation fails by throwing an exception if the AST is currently locked. This pointer still exists and any operation that would normally reinstantiate the AST (such as pointer dereference) will do so.

Thread safety: This function is thread safe.

operator==() [1/2]

bool Rose::BinaryAnalysis::InstructionPtr::operator==

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator!=() [1/2]

bool Rose::BinaryAnalysis::InstructionPtr::operator!=

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator<=()

bool Rose::BinaryAnalysis::InstructionPtr::operator<=

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator>=()

bool Rose::BinaryAnalysis::InstructionPtr::operator>=

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator<()

bool Rose::BinaryAnalysis::InstructionPtr::operator<

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator>()

bool Rose::BinaryAnalysis::InstructionPtr::operator>

(

const InstructionPtr &

other

)

const

Comparison.

Thread safety: This function is thread safe.

operator==() [2/2]

bool Rose::BinaryAnalysis::InstructionPtr::operator==

(

std::nullptr_t

)

const

Comparison.

Thread safety: This function is thread safe.

operator!=() [2/2]

bool Rose::BinaryAnalysis::InstructionPtr::operator!= ( std::nullptr_t  ) const

inline

Comparison.

Thread safety: This function is thread safe.

Definition at line 524 of file InstructionCache.h.

References lock().

---

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

• InstructionCache.h