Finish mucking around with pointer based option

Author: znicholls

src/example_fgen_basic/error_v/error_v.f90

@@ -92,6 +92,8 @@ subroutine finalise(self)
         ! Hopefully can leave without docstring (like Python)
 
         ! If we make message allocatable, deallocate here
+        self % code = 1
+        self % message = ""
 
     end subroutine finalise
 

src/example_fgen_basic/error_v/error_v.py

@@ -13,6 +13,7 @@
     FinalisableWrapperBasePtrBased,
     check_initialised,
     check_initialised_ptr_based,
+    execute_finalise_on_fail_ptr_based,
 )
 from example_fgen_basic.pyfgen_runtime.exceptions import CompiledExtensionNotFoundError
 
@@ -106,7 +107,77 @@ def exposed_attributes(self) -> tuple[str, ...]:
         """
         return ("code", "message")
 
+    @classmethod
+    def from_new_connection(cls) -> ErrorVPtrBased:
+        """
+        Initialise from a new connection
+
+        The user is responsible for releasing this connection
+        using :attr:`~finalise` when it is no longer needed.
+        Alternatively a :obj:`~AtmosphereToOceanCarbonFluxCalculatorContext`
+        can be used to handle the finalisation using a context manager.
+
+        Returns
+        -------
+            A new instance with a unique instance index
+
+        Raises
+        ------
+        WrapperErrorUnknownCause
+            If a new instance could not be allocated
+
+            This could occur if too many instances are allocated at any one time
+        """
+        instance_ptr = m_error_v_ptr_based_w.get_instance_ptr()
+        # TODO: result type handling here
+
+        return cls(instance_ptr)
+
     # TODO: from_build_args, from_new_connection, context manager, finalise
+    @classmethod
+    def from_build_args(
+        cls,
+        code: int,
+        message: str = "",
+    ) -> ErrorVPtrBased:
+        """
+        Build the class (including connecting to Fortran)
+        """
+        out = cls.from_new_connection()
+        # TODO: remove or update this construct when we have result types
+        execute_finalise_on_fail_ptr_based(
+            out,
+            m_error_v_ptr_based_w.instance_build,
+            code=code,
+            message=message,
+        )
+
+        return out
+
+    @check_initialised
+    def finalise(self) -> None:
+        """
+        Close the connection with the Fortran module
+        """
+        m_error_v_ptr_based_w.instance_finalise(self.instance_ptr)
+        self._uninitialise_instance_ptr()
+
+    @property
+    def is_associated(self) -> bool:
+        """
+        Check whether `self`'s pointer is associated on the Fortran side
+
+        Returns
+        -------
+        :
+            Whether `self`'s pointer is associated on the Fortran side
+        """
+        if self.instance_ptr is None:
+            return False
+
+        res: bool = bool(m_error_v_ptr_based_w.is_associated(self.instance_ptr))  # type: ignore
+
+        return res
 
     @property
     @check_initialised_ptr_based

src/example_fgen_basic/error_v/error_v_ptr_based_wrapper.f90

@@ -4,17 +4,127 @@
 !> Generation to be automated in future (including docstrings of some sort).
 module m_error_v_ptr_based_w
 
-    use iso_c_binding, only: c_ptr, c_f_pointer
+    use iso_c_binding, only: c_f_pointer, c_loc, c_null_ptr, c_ptr
 
     use m_error_v, only: ErrorV
 
     implicit none
     private
 
-    public :: iget_code, iget_message
+    public :: get_instance_ptr, instance_build, instance_finalise, is_associated, &
+              iget_code, iget_message
 
 contains
 
+    subroutine get_instance_ptr(res_instance_ptr)
+        !> Get a pointer to a new instance
+        !
+        ! Needs to be subroutine to have the created instance persist I think
+        ! (we can check)
+        ! function create_error(inv) result(res_instance_index)
+
+        !f2py integer(8), intent(out) :: res_instance_ptr
+        type(c_ptr), intent(out) :: res_instance_ptr
+        !! Pointer to the resulting instance
+        !
+        ! This is the major trick for wrapping.
+        ! We return pointers (passed as integers) to Python rather than the instance itself.
+
+        type(ErrorV), pointer :: res
+        ! Question is: when does this get deallocated?
+        ! When we go out of scope?
+        ! If yes, that will be why we had to do this array thing.
+        allocate(res)
+
+        res_instance_ptr = c_loc(res)
+
+    end subroutine get_instance_ptr
+
+    subroutine instance_build(instance_ptr, code, message)
+        !> Build an instance
+
+        !f2py integer(8), intent(in) :: instance_ptr
+        type(c_ptr), intent(in) :: instance_ptr
+        !! Pointer to the instance
+        !
+        ! This is the major trick for wrapping.
+        ! We pass pointers (passed as integers) to Python rather than the instance itself.
+
+        integer, intent(in) :: code
+        character(len=*), optional, intent(in) :: message
+
+        type(ErrorV), pointer :: inst
+
+        call c_f_pointer(instance_ptr, inst)
+
+        call inst % build(code, message)
+
+    end subroutine instance_build
+
+    subroutine instance_finalise(instance_ptr)
+        !> Finalise an instance
+
+        !f2py integer(8), intent(inout) :: instance_ptr
+        type(c_ptr), intent(inout) :: instance_ptr
+        !! Pointer to the instance
+        !
+        ! This is the major trick for wrapping.
+        ! We pass pointers (passed as integers) to Python rather than the instance itself.
+
+        type(ErrorV), pointer :: inst
+
+        call c_f_pointer(instance_ptr, inst)
+
+        ! This may be why we used the array approach.
+        ! The issue here is that, if you call this method twice,
+        ! there is no way to work out that you're the 'second caller'.
+        ! When the first call calls `deallocate(inst)`,
+        ! this puts any other pointers to the instance in an undefined status
+        ! (https://www.ibm.com/docs/en/xl-fortran-aix/16.1.0?topic=attributes-deallocate).
+        ! The result of calling associated on an undefined pointer
+        ! can be anything (https://stackoverflow.com/questions/72140217/can-you-test-for-nullpointers-in-fortran),
+        ! i.e. there is no way to tell that someone else
+        ! has already called finalise before you have.
+        ! This also explains the undefined status issue nicely:
+        ! community.intel.com/t5/Intel-Fortran-Compiler/DEALLOCATING-DATA-TYPE-POINTERS/m-p/982338#M100027
+        !
+        ! We'd have to introduce some reference counter to make this work I think.
+        ! Probably better advice for now, don't share pointer values
+        ! on the Python side, you have to be super careful about uninitialising if you do.
+        ! Avoiding pointers and using allocatable instead
+        ! was probably the other reason we did it how we did
+        ! community.intel.com/t5/Intel-Fortran-Compiler/how-to-test-if-pointer-array-is-allocated/m-p/1138643#M136486.
+        if (associated(inst)) then
+            call inst % finalise()
+            deallocate(inst)
+        end if
+
+    end subroutine instance_finalise
+
+    subroutine is_associated(instance_ptr, res)
+        !> Check if a pointer is associated with an instance
+
+        !f2py integer(8), intent(in) :: instance_ptr
+        type(c_ptr), intent(in) :: instance_ptr
+        !! Pointer to the instance
+        !
+        ! This is the major trick for wrapping.
+        ! We pass pointers (passed as integers) to Python rather than the instance itself.
+
+        logical, intent(out) :: res
+        !! Whether `instance_ptr` is associated or not
+
+        type(ErrorV), pointer :: inst
+
+        call c_f_pointer(instance_ptr, inst)
+
+        print *, instance_ptr
+        print *, inst
+        res = associated(inst)
+        print *, res
+
+    end subroutine is_associated
+
     ! Full set of wrapping strategies to pass different types in e.g.
     ! https://gitlab.com/magicc/fgen/-/blob/switch-to-uv/tests/test-data/exposed_attrs/src/exposed_attrs/exposed_attrs_wrapped.f90
     ! (we will do a full re-write of the code which generates this,

src/example_fgen_basic/exceptions.py

@@ -57,7 +57,7 @@ def __init__(self, instance: Any, method: Optional[Callable[..., Any]] = None):
         if method:
             error_msg = f"{instance} must be initialised before {method} is called"
         else:
-            error_msg = f"instance ({instance:r}) is not initialized yet"
+            error_msg = f"instance ({instance:r}) is not initialised yet"
 
         super().__init__(error_msg)
 

src/example_fgen_basic/pyfgen_runtime/base_finalisable.py

@@ -77,7 +77,7 @@ def _repr_html_(self) -> str:
         )
 
     @property
-    def initialized(self) -> bool:
+    def initialised(self) -> bool:
         """
         Is the instance initialised, i.e. connected to a Fortran instance?
         """
@@ -108,7 +108,7 @@ def exposed_attributes(self) -> tuple[str, ...]:
     #     ...
     #
     # @abstractmethod
-    # def finalize(self) -> None:
+    # def finalise(self) -> None:
     #     """
     #     Finalise the Fortran instance and set self back to being uninitialised
     #
@@ -157,7 +157,7 @@ def checked(
         *args: P.args,
         **kwargs: P.kwargs,
     ) -> Any:
-        if not ref.initialized:
+        if not ref.initialised:
             raise NotInitialisedError(ref, method)
 
         return method(ref, *args, **kwargs)
@@ -210,7 +210,7 @@ def _repr_html_(self) -> str:
         )
 
     @property
-    def initialized(self) -> bool:
+    def initialised(self) -> bool:
         """
         Is the instance initialised, i.e. connected to a Fortran instance?
         """
@@ -224,37 +224,36 @@ def exposed_attributes(self) -> tuple[str, ...]:
         """
         ...
 
-    # TODO: consider whether we need these
-    # @classmethod
-    # @abstractmethod
-    # def from_new_connection(cls) -> FinalisableWrapperBase:
-    #     """
-    #     Initialise by establishing a new connection with the Fortran module
-    #
-    #     This requests a new model index from the Fortran module and then
-    #     initialises a class instance
-    #
-    #     Returns
-    #     -------
-    #     New class instance
-    #     """
-    #     ...
-    #
-    # @abstractmethod
-    # def finalize(self) -> None:
-    #     """
-    #     Finalise the Fortran instance and set self back to being uninitialised
-    #
-    #     This method resets `self.instance_ptr` back to
-    #     `None`
-    #
-    #     Should be decorated with :func:`check_initialised`
-    #     """
-    #     # call to Fortran module goes here when implementing
-    #     self._uninitialise_instance_index()
+    @classmethod
+    @abstractmethod
+    def from_new_connection(cls) -> FinalisableWrapperBase:
+        """
+        Initialise by establishing a new connection with the Fortran module
 
-    def _uninitialise_instance_index(self) -> None:
-        self.instance_index = None
+        This requests a new model index from the Fortran module and then
+        initialises a class instance.
+
+        Returns
+        -------
+        :
+            New class instance
+        """
+        ...
+
+    @abstractmethod
+    def finalise(self) -> None:
+        """
+        Finalise the Fortran instance and set self back to being uninitialised
+
+        This method resets `self.instance_ptr` back to `None`.
+
+        Should be decorated with :func:`check_initialised`
+        """
+        # call to Fortran module goes here when implementing
+        self._uninitialise_instance_ptr()
+
+    def _uninitialise_instance_ptr(self) -> None:
+        self.instance_ptr = None
 
 
 WrapperPtrBased = TypeVar("WrapperPtrBased", bound=FinalisableWrapperBasePtrBased)
@@ -288,9 +287,59 @@ def checked(
         *args: P.args,
         **kwargs: P.kwargs,
     ) -> Any:
-        if not ref.initialized:
+        if not ref.initialised:
             raise NotInitialisedError(ref, method)
 
         return method(ref, *args, **kwargs)
 
     return checked  # type: ignore
+
+
+# Thank you for type hints info
+# https://adamj.eu/tech/2021/05/11/python-type-hints-args-and-kwargs/
+def execute_finalise_on_fail_ptr_based(
+    inst: FinalisableWrapperBasePtrBased,
+    func_to_try: Callable[Concatenate[int, P], T],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> T:
+    """
+    Execute a function, finalising the instance before raising if any error occurs
+
+    This function is most useful in factory functions where it provides a
+    clean way of ensuring that any Fortran is freed up in the event of an
+    initialisation failure for any reason
+
+    Parameters
+    ----------
+    inst
+        Instance whose model index we will use when executing the functin
+
+    func_to_try
+        Function to try executing, must take `inst`'s instance pointer as its
+        first argument
+
+    *args
+        Passed to `func_to_try`
+
+    **kwargs
+        Passed to `func_to_try`
+
+    Returns
+    -------
+    :
+        Result of calling `func_to_try(inst.instance_ptr, *args, **kwargs)`
+
+    Raises
+    ------
+    Exception
+        Any exception which occurs when calling `func_to_try`. Before the
+        exception is raised, `inst.finalise()` is called.
+    """
+    try:
+        return func_to_try(inst.instance_ptr, *args, **kwargs)
+    except RuntimeError:
+        # finalise the instance before raising
+        inst.finalise()
+
+        raise