Document using atexit for module destructors

[bmerry]

None of the three currently recommended approaches works on PyPy, due to
it not garbage collecting things when you want it to. Added an example
showing how to get interpreter shutdown callbacks using the Python
atexit module, and added a note that the other approaches are not
portable.

[wjakob]

Objects not being garbage collected at interpreter shutdown sounds like a serious PyPy issue to me (which will also manifest itself in other situations). Rather than rewriting the current documentation, I'd prefer it note that you add a ".. note" about this flaw in PyPy, pointing out your proposed alternative approach.

[bmerry]

Okay, I've taken another stab at it (not flattened yet).

In case you want to file a bug against PyPy, here's the code I used to check the support for the different approaches in each interpreter:

#include <pybind11/pybind11.h>
#include <iostream>

namespace py = pybind11;

class A {};

PYBIND11_MODULE(destructor, m) {
    m.add_object("_cleanup", py::capsule([] () { std::cerr << "Cleanup 1\n"; }));

    py::class_<A> A_class(m, "A");
    A_class.attr("_cleanup") = py::capsule([] () { std::cerr << "Cleanup 2\n"; });

    py::cpp_function cleanup_callback(
        [](py::handle weakref) {
            std::cerr << "Cleanup 3\n";
            weakref.dec_ref();
        }
    );
    (void) py::weakref(A_class, cleanup_callback).release();

    auto atexit = py::module::import("atexit");
    atexit.attr("register")(py::cpp_function([]() {
        std::cerr << "Cleanup 4\n";
    }));
}

[wjakob]

The updated PR looks good to me. Regarding PyPy: my experience has been that they much prefer bug reports which use pure CPython API.

[bmerry]

@wjakob are you waiting for something before merging?

[jagerman]

The note seems fine to me, as well. Merged.