Reference Counter

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

Overview

Reference Counter offers semi-automatic counting of references to program resources such as memory. A user accesses the provided reference-counting capability simply by defining a non-abstract derived type that

1. Extends Reference Counter's ref_reference_t type and
2. Implements the so-inherited free deferred binding.

Because the reference-counting algorithm involves copying references in certain circumstances, the user type that extends sref_reference_t should be a lightweight proxy for a more stateful entity stored elsewhere. For example, the user type might contain a Fortran pointer associated with some other object or it might contain a "shadow" object that serves as an identity tag for a larger object allocated (and later freed) in C or C++ at the direction of the user's free procedure.

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

As compared to the original code, this repository also adds

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

Documentation

See Reference Counter's GitHub Pages site for HTML documentation generated with ford.

See the doc/ subdirectory for a PlantUML script that generates the Unified Modeling Langauge (UML) class diagram below of the three derived types in reference-counter.

The above image was created with the PlantuML package in the Atom editor.

Compiler Status

Correct execution of the Reference Counter library code requires comprehensive compiler support for Fortran's type finalization semantics. The unit test suite includes compiler standard-conformance tests. We have attempted to include at least one example of each scenario in which the Fortran 2018 standard requires compilers to finalize objects. The table below summarizes the observed compiler behaviors:

Compiler	Test failures	Version tested
NAG	0	nagfor 7.1 Build 7113
GCC	6	gfortran 12.2.0
Intel	2	ifort 2021.5.0 Build 20211109_000000
NVIDIA	Fails to build (ICE)	nvfortran 2022.2
AMD	Fails to build (ICE)	flang 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 failures.

Downloading, Building, and Testing

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

git clone git@github.com:sourceryinstitute/reference-counter
cd reference-counter

followed by one of the commands below depending on your compiler choice.

GCC (gfortran)

fpm test

Numerical Algorithms Group (nagfor)

fpm test --compiler nagfor --flag -fpp

Intel (ifort)

fpm test --compiler ifort --flag -coarray=shared

NVIDIA (nvfortran)

fpm test --compiler nvfortran --flag -Mpreprocess

AMD (flang)

fpm test --compiler flang --flag -cpp