Clarify plugin lifecycle and hide eventhdlr bookkeeping

Author: Joao-Dionisio

CHANGELOG.md

@@ -7,7 +7,7 @@
 ### Fixed
 - Removed `Py_INCREF`/`Py_DECREF` on `Model` in `catchEvent`/`dropEvent` that caused memory leak for imbalanced usage
 - Used `getIndex()` instead of `ptr()` for sorting nonlinear expression terms to avoid nondeterministic behavior
-- Replaced `weakref.proxy` with strong references for plugin `self.model`, fixing `ReferenceError` during cleanup callbacks (#1193)
+- Plugins now hold strong references to their `Model` instead of `weakref.proxy`, fixing `ReferenceError` during cleanup callbacks (#1193)
 ### Changed
 - Speed up `constant * Expr` via C-level API
 ### Removed

src/pyscipopt/event.pxi

@@ -3,7 +3,8 @@
 cdef class Eventhdlr:
     cdef public Model model
     cdef public str name
-    cdef public list _caught_events
+    # eventtypes caught via `Model.catchEvent`, auto-dropped on `eventexit`.
+    cdef list _caught_events
 
     def __cinit__(self):
         self._caught_events = []

src/pyscipopt/scip.pxd

@@ -2251,7 +2251,11 @@ cdef class Model:
     cdef int _generated_event_handlers_count
     # store references to Benders subproblem Models for proper cleanup
     cdef _benders_subproblems
-    # store references to plugins for the Model <-> Plugin reference cycle
+    # Strong references to every included plugin. Each plugin in turn holds a
+    # strong reference to the Model via `self.model`, so both stay alive until
+    # SCIP teardown callbacks (consfree, eventexit, ...) have finished running.
+    # The resulting cycle is broken by `Model.__del__` or by `Model.free()`.
+    # See `Model.free` for the full lifecycle policy.
     cdef _plugins
     # store iis, if found
     cdef SCIP_IIS* _iis

src/pyscipopt/scip.pxi

@@ -2899,19 +2899,16 @@ cdef class Model:
         self.includeEventhdlr(event_handler, name, description)
 
     def __del__(self):
-        """Free SCIP before the cyclic GC clears Python references.
+        """Free SCIP when the last external reference to the Model is dropped.
 
-        __del__ (tp_finalize) runs before tp_clear, so _plugins and other
-        Python attributes are still intact. This lets SCIPfree call plugin
-        callbacks (consfree, eventexit, etc.) safely. The GC handles breaking
-        the circular references afterwards via tp_clear.
+        Runs before the garbage collector clears the Model's attributes, so
+        plugin callbacks can still reach a live ``self.model``. See
+        ``Model.free`` for the full lifecycle policy.
         """
         self._free_scip_instance()
 
     def __dealloc__(self):
-        # Safety net: if __del__ didn't run (e.g. interpreter shutdown),
-        # free SCIP here. Plugin callbacks may not work at this point since
-        # tp_clear may have already cleared _plugins.
+        """Fallback SCIP cleanup if ``__del__`` did not already free the instance."""
         if self._scip is not NULL and self._freescip:
             SCIPfree(&self._scip)
 
@@ -3089,11 +3086,28 @@ cdef class Model:
         PY_SCIP_CALL(SCIPfreeProb(self._scip))
 
     def free(self):
-        """Explicitly free SCIP instance and break circular references with plugins.
-
-        This method should be called when you want to ensure deterministic cleanup.
-        All SCIP callbacks (consfree, eventexit, etc.) are executed during this call.
-        After calling this method, the Model object should not be used anymore.
+        """Explicitly free the SCIP instance and release plugin references.
+
+        Every included plugin holds a strong reference to its Model via
+        ``self.model``, and the Model holds strong references to every plugin
+        via ``Model._plugins``. This cycle is intentional: it keeps both sides
+        alive during SCIP teardown so callbacks such as ``eventexit`` and
+        ``consfree`` can safely reach ``self.model``.
+
+        The cycle is broken in one of two ways:
+
+        * Implicitly, via ``Model.__del__`` when the last external reference to
+          the Model is dropped. ``__del__`` runs before the garbage collector
+          (GC) clears attributes, so callbacks still see a live ``self.model``.
+          Timing is at the GC's discretion.
+        * Explicitly, by calling this method. SCIP is freed immediately,
+          teardown callbacks fire before ``free`` returns, and the plugin list
+          is cleared. Use this when deterministic cleanup is required. After
+          ``free`` the Model must not be used further.
+
+        The solve itself is not affected by which path runs. ``free`` only
+        controls when memory and resources are released, and when teardown
+        callbacks execute.
         """
         self._free_scip_instance()
 

src/pyscipopt/scip.pyi

@@ -315,7 +315,6 @@ class Event:
 class Eventhdlr:
     model: Incomplete
     name: Incomplete
-    _caught_events: list
     def __init__(self) -> None: ...
     def eventcopy(self) -> Incomplete: ...
     def eventdelete(self) -> Incomplete: ...

tests/test_event.py

@@ -200,8 +200,7 @@ def eventexec(self, event):
     with pytest.raises(Exception):
         m.optimize()
 
-    del m, ev, v
-    gc.collect()
+    m.free()
 
 def test_missing_dropEvent_cleanup():
     """Model is garbage collected even when dropEvent is not called in eventexit."""