[GRASS-git] [OSGeo/grass] 23a8e6: libgis: Distinguish dirs and objects in dir creati...

[Vaclav Petras]

  Branch: refs/heads/master
  Home:   https://github.com/OSGeo/grass
  Commit: 23a8e6d786b332b1e3379d373a101f9dc2e76494
      https://github.com/OSGeo/grass/commit/23a8e6d786b332b1e3379d373a101f9dc2e76494
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2021-07-13 (Tue, 13 Jul 2021)

  Changed paths:
    M general/g.filename/main.c
    M include/grass/defs/gis.h
    M lib/db/dbmi_base/default_name.c
    M lib/gis/mapset_msc.c
    M lib/gis/open.c
    M lib/gis/tempfile.c
    M lib/manage/do_copy.c
    M lib/raster/close.c
    M lib/raster/gdal.c
    M lib/raster/open.c
    M lib/raster/quant_io.c
    M lib/raster3d/mapset.c
    M lib/vector/Vlib/map.c

  Log Message:
  -----------
  libgis: Distinguish dirs and objects in dir creation (#1681)

The G_make_mapset_element() function is used in several places to create
nested directories such as grid3/some_raster3d_name for particular maps/objects.
However, the original purpose of G_make_mapset_element() seems to be creating directories
(such as fcell, vector) for these objects (objects such as elevation or bridges).

This change introduces new API functions which make distinction between these scenarios.
One function is for what most of the original API calls element that is the directory
for objects of the same type. The other is for the objects themselves.

The three new functions replace two existing ones.
Two replace G_make_mapset_element() covering the two cases and one replaces
G_make_mapset_element_tmp() covering only the common directory case
because there is no direct use of this functionality in the current code.
In the new API, dir_object is for the vector/name case and object_group for the vector and fcell cases.
The vector/name case is a single function call with more parameters rather than two function calls
and replaces the use of %s/%s syntax which is what was used before.

Distinguishing the two scenarios allows the code to handle differently a race
condition during creation when another process creates the same directory
between the failed access call and mkdir call.

In case of directory such as fcell or vector, all we asked
for was that the directory exists at the end of the function call which
will be fulfilled even when mkdir happened in another process.

Same race condition for directories such as cell_misc/raster_map_name or vector/vector_map_name
is actual problem and reporting it sooner rather than later is advantageous in
detecting the issue (assuming that the issue is two processes are trying to create map of the same name).
However, this is not the new behavior for some vector files where %s/%s syntax is still used
to create the parent directories without making any distinctions about the purpose of the directory.
This is the behavior which the code had before 3c374600e3cc7d91c542cab4411fdf40f31ce931
which was intended to imporve error message, but it changed also the the on-creation-race behavior.

The underlying issue seems to be, at least partially, the unclear naming. Element sometimes refers to
the particular file such as fcell/raster_map_name, but in the G_make functions, it refers to the
directory of these files such as fcell. This new API does not use any great names,
but the idea is to refer to element group directories (such as cell) and specific
element files or directories (raster map piece, sub-directory for a specific vector map).
The hope is that in the new API, words directory, object, and type are used in somewhat common way.

Creation of misc elements (cell_misc and group) is now the two-phase creation of an object which is a dir. Function is internal (double underscore after G), used consistently, and documented such that element is the name of the concrete object, so keeping the name as is.

The documentation of functions is based on the current usage and new names although the terminology is not a new official terminology.