Detailed Description

Call policy for a binding that hands out an object owned by something else, such as a gate of a netlist or a gate type of a gate library.

Use it wherever py::return_value_policy::reference_internal was used before. It hands the object over without ownership, exactly as that policy did, but decides differently what has to stay alive and when that decision is made.

It requests py::return_value_policy::reference, which creates a non-owning wrapper and links nothing, and then establishes every link itself. reference_internal cannot be used underneath: it calls keep_alive_impl(instance, parent) while the wrapper is being created, which would add a link to the receiver on top of the one added here.

Two things it does that the policy does not:

It links unconditionally. reference_internal is only honoured while a wrapper is being created; when pybind11 finds that the object already has one it returns that wrapper immediately and applies neither the policy nor any keep_alive. Whether an object was protected therefore depended on which binding happened to hand it over first, and one unprotected path was enough to leave it unprotected everywhere.
It keeps the owner alive rather than the object the binding was called on. A module read from a gate stays valid because the netlist stays alive, not because that gate does, and the netlist is also what owns it. Linking to the receiver instead would tie the module to the gate while the gate can be read back from the module, closing a reference cycle; pybind11 instances are not tracked by the garbage collector, so such a cycle is never collected, and making the link unconditional would have turned an order dependence into a permanent leak.

The owner is only ever resolved through a wrapper that already exists. Constructing one is deliberately avoided, as that would hand a borrowed pointer to a holder and could open a second ownership group over an object that is already owned elsewhere.

Definition at line 129 of file python_bindings.h.

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

include/hal_core/python_bindings/python_bindings.h