Should all implementations be placed in submodules?

[ivan-pi]

From @milancurcic in #539:

General question for everybody, do we have a guide on when to put a function implementation in its own submodule and when to leave it in the module? I see that we have clip in the module but the others have their own submodules.

On the long term I think the public modules should contain only the interfaces, and all of the implementation should be placed in sub-modules. This would facilitate compiler vendors providing their own optimized implementations in the (distant?) future. It would also make it easier to swap between debug and release binaries by re-linking. I think the current reasoning was simply when launching a new module with a small function, it was just easier to prepare a single module.

A second reason in favor of separating interface and implementation might be to use a stdlib library compiled by another Fortran compiler. In this case you would only need to compile the interface (see https://github.com/fortran-lang/stdlib/pull/530#discussion_r711945701 and the discussion that follows). As an example, Intel MKL ships libraries that can be used with both Intel and gfortran compilers.

Originally posted by @ivan-pi in https://github.com/fortran-lang/stdlib/issues/539#issuecomment-927824562

[milancurcic]

It makes sense to me, I agree.

Another advantage to submodules in their own source files is that the implementations that are independent from one another could be compiled in parallel.

[Beliavsky]

There is an abbreviated version of submodules that I think should be avoided. Here is an example of it from the Fortran Wiki:

submodule (points) points_a
contains
  module procedure point_dist
    distance = sqrt((a%x - b%x)**2 + (a%y - b%y)**2)
  end procedure point_dist
end submodule points_a

I don't want to guess a procedure's arguments or look at another source file for them.

[ivan-pi]

A few issues semi-related to submodules:

• NAG 7.0 is required to support submodules, see #108
• CMake version 3.16.3 is required to support submodules, see #108
• In #307 I advocate the separation of interface and implementation using submodules as a way to provide non-Fortran implementations of stdlib functionality using existing C or C++ libraries (like Boost)

Besides avoiding compilation cascades during development, another benefit of submodules is the reduction in memory usage during compilation (see https://github.com/fortran-lang/stdlib/pull/283).

Another important usage of submodules would be to swap between implementations with different backends or performance tradeoffs. Some examples:

• in a high-level linear algebra interface we could swap between LAPACK or libFLAME as the backend
• a high-level fft subroutine could switch between FFTPACK, pocketfft, fftw or other FFT libraries
• a cubic spline module could be based upon a reference Fortran-only implementation or call the Intel MKL Data Fitting Functions.