This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
TfPyObjWrapper Class Reference

Boost Python object wrapper. More...

#include <pyObjWrapper.h>

+ Inheritance diagram for TfPyObjWrapper:

Public Member Functions

TF_API TfPyObjWrapper ()
 Default construct a TfPyObjWrapper holding a reference to python None.
 
TF_API TfPyObjWrapper (object obj)
 Construct a TfPyObjectWrapper wrapping obj.
 
object const & Get () const
 Underlying object access.
 
TF_API PyObject * ptr () const
 Underlying PyObject* access.
 
TF_API bool operator== (TfPyObjWrapper const &other) const
 Equality.
 
TF_API bool operator!= (TfPyObjWrapper const &other) const
 Inequality.
 

Friends

class pxr_boost::python::api::object_operators< TfPyObjWrapper >
 
size_t hash_value (TfPyObjWrapper const &o)
 Produce a hash code for this object.
 

Detailed Description

Boost Python object wrapper.

Provides a wrapper around pxr_boost::python::object that works correctly for the following basic operations regardless of the GIL state: default construction, copy construction, assignment, (in)equality comparison, hash_value(), and destruction.

None of those work correctly in the presence of an unlocked GIL for pxr_boost::python::object. This class only actually acquires the GIL for default construction, destruction and for some (in)equality comparisons. The other operations do not require taking the GIL.

This is primarily useful in cases where a pxr_boost::python::object might be destroyed without a locked GIL by a client blind to that fact. This occurs when a registry, for example, holds type-erased objects. If one of the type-erased objects in the registry happens to hold a pxr_boost::python::object, that type-erased object must be destroyed while the GIL is held but it's unreasonable to require that the registry know that. This class helps solve that problem.

This class also provides many of the operators that pxr_boost::python::object provides, by virtue of deriving from pxr_boost::python::api::object_operators<T>. However it is important to note that callers must ensure the GIL is held before using these operators!

Definition at line 77 of file pyObjWrapper.h.

Constructor & Destructor Documentation

◆ TfPyObjWrapper() [1/2]

TF_API TfPyObjWrapper ( )

Default construct a TfPyObjWrapper holding a reference to python None.

The GIL need not be held by the caller.

◆ TfPyObjWrapper() [2/2]

TF_API TfPyObjWrapper ( object  obj)

Construct a TfPyObjectWrapper wrapping obj.

The GIL must be held by the caller. Note, allowing the implicit conversion is intended here.

Member Function Documentation

◆ Get()

object const & Get ( ) const
inline

Underlying object access.

This method returns a reference, so technically, the GIL need not be held to call this. However, the caller is strongly advised to ensure the GIL is held, since assigning this object to another or otherwise operating on the returned object requires it.

Definition at line 98 of file pyObjWrapper.h.

◆ operator!=()

TF_API bool operator!= ( TfPyObjWrapper const &  other) const

Inequality.

Returns false if other refers to the same python object.

◆ operator==()

TF_API bool operator== ( TfPyObjWrapper const &  other) const

Equality.

Returns true if other refers to the same python object.

◆ ptr()

TF_API PyObject * ptr ( ) const

Underlying PyObject* access.

This method returns a pointer, so technically, the GIL need not be held to call this. However, the caller is strongly advised to ensure the GIL is held, since assigning this object to another or otherwise operating on the returned object requires it. The returned PyObject * is a "borrowed reference", meaning that the underlying object's reference count has not been incremented on behalf of the caller.

Friends And Related Function Documentation

◆ hash_value

size_t hash_value ( TfPyObjWrapper const &  o)
friend

Produce a hash code for this object.

Note that this does not attempt to hash the underlying python object, it returns a hash code that's suitable for hash-table lookup of TfPyObjWrapper instances, and does not require taking the python lock.

Definition at line 115 of file pyObjWrapper.h.

◆ pxr_boost::python::api::object_operators< TfPyObjWrapper >

friend class pxr_boost::python::api::object_operators< TfPyObjWrapper >
friend

Definition at line 125 of file pyObjWrapper.h.


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