sourceryinstitute/smart-pointers

An object-oriented, extensible reference-counting utility for Fortran

Smart Pointers

  _________                      __                 
 /   _____/ _____ _____ ________/  |_               
 \_____  \ /     \\__  \\_  __ \   __\              
 /        \  Y Y  \/ __ \|  | \/|  |                
/_______  /__|_|  (____  /__|   |__|                
        \/      \/     \/                           
__________      .__        __                       
\______   \____ |__| _____/  |_  ___________  ______
 |     ___/  _ \|  |/    \   __\/ __ \_  __ \/  ___/
 |    |  (  <_> )  |   |  \  | \  ___/|  | \/\___ \ 
 |____|   \____/|__|___|  /__|  \___  >__|  /____  >
                        \/          \/           \/ 
                             \/            

Overview

The Smart-Pointers library tracks references to program resources and automates the freeing of those resources if and only if the reference count drops to zero. Most commonly, the reference is a pointer and the resource is memory. In that context, Smart-Pointers help to prevent memory leaks and dangling pointers, which commonly causes programs to crash due to memory limitations or segmentation faults, respectively.

To use Smart-Pointers, define a non-abstract derived type that

1. Extends Smart-Pointer's sp_smart_pointer_t type,
2. Implements the inherited free deferred binding, and
3. Invokes the inherited start_count procedure inside object constructors.

You can then use intrinsic assignments to copy instances of a sp_smart_pointer_t child type, resulting in a shallow copy with the advantage that the target will be finalized only when it becomes safe to do so.

Example

See the example folder for a demonstration of the use of Smart-Pointers.

Background

For more background on the design philosophy and the internal mechanics of Smart Pointers, see Rouson et al. (see [1], [2], [3]). This repository's code originated from refactoring the code in those publications to use more up-to-date coding conventions. For example, this repository separates interface bodies into modules and procedure definitions into submodules. This repository also uses more descriptive nomenclature for the types and procedures.

This repository also adds

1. A Fortran Package Manager build system,
2. Tests based on the Sourcery library's unit-testing utility,
3. Documentation generated by ford and deployed to the web via GitHub Actions, and
4. Quality control via continuous integration testing using GitHub Actions.

Supported Compilers

Correct execution of the Smart-Pointers library depends critically on comprehensive compiler support for type finalization. The unit test suite verifies the relevant compiler standard-conformance, including a test for each scenario in which the the Fortran 2023 standard requires that an object be finalized. The following compilers pass all Smart-Pointers tests:

Compiler	Test failures	Version tested
GCC gfortran 🏆	0	13.1.0
LLVM flang 🏆	0	19.0.0 git commit 325f5123
NAG nagfor 🏆	0	7.1 Build 7113

Partially Supported Compilers

The following compilers pass most smart pointers tests:

Compiler	Test failures	Version tested
Cray ftn	4	17.0.0
IBM xlf2008_r	1	17.1.0 on AIX
Intel ifort	1	2021.7.0 Build 20220726_000000
Intel ifx	1	2024.0.0 Build 20231017
NVIDIA nvfortran	2	22.7-0

Unsupported Compiler

The following compiler fails to build Smart-Pointers due to an internal compiler error (ICE):

Compiler	Test failures	Version tested
AMD flang	N.A. (see Note)	13.0.0 (AOCC_3.2.0-Build#128 2021_11_12)

See the test suite README.md for more details on each compiler's test results.

Downloading, Building, and Testing

On Linux, macOS, or Windows Subsystem for Linux, download, build, and test with the following shell commands:

git clone https://github.com/sourceryinstitute/smart-pointer
cd smart-pointer

followed by one of the commands below corresponding to your compiler choice.

Fully supported compilers

The following compilers pass all Smart-Pointers tests.

GCC gfortran

fpm test

LLVM flang

fpm test --compiler flang-new

NAG nagfor

fpm test --compiler nagfor --flag -fpp

Partially supported compilers

The following compilers pass most Smart-Pointers tests.

HPE: Cray Compiler Environment (CCE)

Building with fpm using the CCE ftn compiler wrapper requires an additional wrapper to identify the wrapped compiler. Place a file named crayftn.sh at the front of your PATH environment variable containing the following contents:

#!/bin/bash

ftn "$@"

Then test with the following command

fpm test --compiler crayftn.sh

IBM

fpm test --archiver ar --compiler xlf2008_r --flag -DXLF

Intel ifort

fpm test --compiler ifort

Intel ifx

fpm test --compiler ifx --flag "-check all,nouninit"

where fpm 0.10.0 or later is required and the --flag argument is required to circumvent what appears to be a bug in ifx's Memory Sanitizer.

NVIDIA nvfortran

fpm test --compiler nvfortran --flag -Mpreprocess

Unsupported compiler

The following compiler cannot build the Smart-Pointers library.

AMD flang

fpm test --compiler flang --flag -cpp

Documentation

See the Smart-Pointers GitHub Pages site for HTML documentation generated with ford. See the doc/ subdirectory for a PlantUML script that generates the Unified Modeling Language (UML) class diagram below of the three derived types in Smart-Pointers.

smart-pointers's Issues

The check_for_leaks test isn't actually referencing the "memory"

It appears that resource created in the test never assigns to the ref_status array, and so all its values remain never_referenced. Thus it appears there is no memory leak, not because all the "acquired" resources are free, but because no resources are ever acquired in the first place.

One %grab too many

In line 23 of ref_counter.f90, the call to %grab() should be commented.
Indeed, the procedure for creating a new (user-defined) object is to call register_self; now, at line 20 of universal.f90, there is an assignment; the assignment already executes a %grab (line 47 ref_counter.f90), and if you leave the %grab at line 23 uncommented, you end up with one %grab too many, resulting in a pointer that never reaches a count of 0, and therefore is never deallocated.

`ctest` failure

I compiled the freshly cloned library on my laptop (i5-6300U) with GFortran 10 on Ubuntu 20.04.3 amd64 LTS using the provided instructions in the README file. GCC was installed from default Ubuntu repos using sudo apt install gfortran-10, and CMake was installed from the official Kitware PPA.
The error in question is:

Test project /home/wyp/work/reference-counter/build
    Start 1: count-leaks
1/1 Test #1: count-leaks ......................***Failed  Required regular expression not found. Regex=[Test passed.
]  0.01 sec

Here are the relevant version strings:

$ uname -a
Linux wyp-ThinkPad-13 5.11.0-43-generic #47~20.04.2-Ubuntu SMP Mon Dec 13 11:06:56 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

$ cat /etc/issue
Ubuntu 20.04.3 LTS \n \l

$ gfortran-10 --version
GNU Fortran (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0
Copyright (C) 2020 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

$ cmake --version
cmake version 3.22.1

CMake suite maintained and supported by Kitware (kitware.com/cmake).

The full terminal log can be accessed here

Fortran runtime error: Attempt to DEALLOCATE unallocated 'the_resource' with Spack GCC 12.1

Looks like Spack GCC 12.1 caught a runtime error:

At line 42 of file test/usage_test.f90
Fortran runtime error: Attempt to DEALLOCATE unallocated 'the_resource'

To replicate:

$ docker pull spack/ubuntu-jammy
$ docker run -it spack/ubuntu-jammy
# spack install [email protected]
# spack load [email protected]
# cd
# git clone https://github.com/fortran-lang/fpm.git
# cd fpm
# ./install.sh
# export PATH=${PATH}:/root/.local/bin
# cd
# git clone https://github.com/sourceryinstitute/reference-counter.git
# cd reference-counter
# fpm test

Fault-tolerant testing

The current test suite has one main driver program, which has the following consequences:

• A compile-time error on one test means no tests can be compiled and run and
• A runtime error in one test means no subsequent tests can run.

To circumvent the above problems, it would be nice to have multiple drivers. Options include

1. One driver for compiler tests and a separate one for usage tests,
2. One driver for each check function in the test suite, or
3. Something between these two extremes, e.g., a separate driver for each of the currently problematic check functions.

Submit bug report to NAG about finalization in specification expressions

Specifically, look at and try to reproduce missing finalization in specification expression.

Naming scheme

It would probably be a good idea to add a unique prefix (something like "xyz_") to the visible entity names for this library, so as to make integration into other codes easier and/or more consistent with existing practices.

Run test suite in CI

With the release of gfortran 13, all tests pass so let's add a CI script that runs this repository's tests suite as a check on pushes and pull requests.

add topics

Topics to add in About section could be garbage-collection, reference-counting.

Test case description not accurate

The description for test case "finalizes a non-pointer non-allocatable array object at the END statement" is not correct, as the actual object in the test is not an array.

Review Test Suite

I'm going to do a review of the test suite, specifically looking at situations involving finalization, and thinking about detecting object creation.