Do only the cleanup of the mapset and exit.
+
Parameters:
@@ -451,6 +465,61 @@ Using temporary mapset
so the script is expected to export, link or otherwise preserve the
output data before ending.
+Multiple sessions in one mapset
+
+Multiple processes in GRASS GIS can run parallel in two basic ways.
+First, the processes can run in multiple sessions each using its own
+mapset (a mapset created by the user or on-the-fly by
+--tmp-mapset). This option often requires management of mapsets
+and collection of data from multiple mapsets, but it is the most robust
+one. Second, some processes, for example most of the raster operations,
+can run in parallel in one mapset. Although this typically means
+running in one session connected to one mapset, this can be also done
+by starting multiple sessions using --exec connected to one
+mapset. In this case, the standard mapset locking and cleaning needs to
+be disabled using --no-lock and --no-clean. This is
+advantageous when it is not possible to have all the parallel processes
+started within one session, for example, when each process is running
+on a different machine.
+
+
+In the following example, let's assume that a Python script called
+run.py was prepared, so that it can run multiple times in
+parallel and it takes one parameter which makes each run unique.
+Another script called post_process_all_runs.py will do
+the post-processing using results from all runs of run.py
+within one mapset.
+
+
+In the first step, let's create a new mapset to be used in the next
+steps:
+
+
+grass79 -e -c /path/to/mapset
+
+grass79 /path/to/mapset --no-lock --no-clean --exec run.py 1
+grass79 /path/to/mapset --no-lock --no-clean --exec run.py 2
+grass79 /path/to/mapset --no-lock --no-clean --exec run.py 3
+grass79 /path/to/mapset --no-lock --no-clean --exec run.py 4
+
+grass79 /path/to/mapset --exec post_process_all_runs.py
+
Troubleshooting
Importantly, to avoid an "[Errno 8] Exec format error" there must be a
diff --git a/lib/init/testsuite/test_grass_clean_lock.py b/lib/init/testsuite/test_grass_clean_lock.py
new file mode 100644
index 00000000000..8b20b5273e6
--- /dev/null
+++ b/lib/init/testsuite/test_grass_clean_lock.py
@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+
+"""
+TEST: Test of grass --tmp-mapset
+
+AUTHOR(S): Vaclav Petras
+
+PURPOSE: Test that --tmp-mapset option of grass command works
+
+COPYRIGHT: (C) 2020 Vaclav Petras and the GRASS Development Team
+
+This program is free software under the GNU General Public
+License (>=v2). Read the file COPYING that comes with GRASS
+for details.
+"""
+
+import unittest
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+
+# Note that unlike rest of GRASS GIS, here we are using unittest package
+# directly. The grass.gunittest machinery for mapsets is not needed here.
+# How this plays out together with the rest of testing framework is yet to be
+# determined.
+
+
+class TestCleanLock(unittest.TestCase):
+ """Tests --no-clean --no-lock options of grass command"""
+
+ # TODO: here we need a name of or path to the main GRASS GIS executable
+ executable = "grass"
+ # an arbitrary, but identifiable and fairly unique name
+ location = "test_tmp_mapset_xy"
+ mapset = os.path.join(location, "PERMANENT")
+
+ def setUp(self):
+ """Creates a location used in the tests"""
+ subprocess.check_call([self.executable, "-c", "XY", self.location, "-e"])
+ self.subdirs = os.listdir(self.location)
+
+ def tearDown(self):
+ """Deletes the location"""
+ shutil.rmtree(self.location, ignore_errors=True)
+
+ def test_command_runs(self):
+ """Check that correct parameters are accepted"""
+ return_code = subprocess.call(
+ [self.executable, self.mapset, "--no-clean", "--exec", "g.proj", "-g"]
+ )
+ self.assertEqual(
+ return_code,
+ 0,
+ msg=(
+ "Non-zero return code from {self.executable}"
+ " with --no-clean".format(**locals())
+ ),
+ )
+
+ return_code = subprocess.call(
+ [self.executable, self.mapset, "--no-lock", "--exec", "g.proj", "-g"]
+ )
+ self.assertEqual(
+ return_code,
+ 0,
+ msg=(
+ "Non-zero return code from {self.executable}"
+ " with --no-lock".format(**locals())
+ ),
+ )
+
+ return_code = subprocess.call(
+ [
+ self.executable,
+ self.mapset,
+ "--no-clean",
+ "--no-lock",
+ "--exec",
+ "g.proj",
+ "-g",
+ ]
+ )
+ self.assertEqual(
+ return_code,
+ 0,
+ msg=(
+ "Non-zero return code from {self.executable}"
+ " with --no-clean and --no-lock".format(**locals())
+ ),
+ )
+
+ return_code = subprocess.call([self.executable, self.mapset, "--clean-only"])
+ self.assertEqual(
+ return_code,
+ 0,
+ msg=(
+ "Non-zero return code from {self.executable}"
+ " with --clean-only".format(**locals())
+ ),
+ )
+
+ def test_clean_only_fails_with_exec(self):
+ """Check that using --clean-only fails when --exec is provided"""
+ return_code = subprocess.call(
+ [self.executable, self.mapset, "--clean-only", "--exec", "g.proj", "-g"]
+ )
+ self.assertNotEqual(
+ return_code,
+ 0,
+ msg=("Zero retrun code from {self.executable}".format(**locals())),
+ )
+
+ def test_cleaning_fake_tmp_file(self):
+ """Check that --no-clean does not delete existing temp files.
+
+ Then it checks that the file is deleted without --no-clean.
+
+ Assumes that clean_temp for cleaning tmp files in mapsets would delete
+ file with name xxx.yyy when there is no process with PID xxx.
+ It further assumes that there is no process with the PID we used,
+ so clean_temp would delete the file.
+ Finally, it assumes the naming and nesting of the tmp dir.
+ """
+ common_unix_max = 32768 # common max of unix PIDs
+ fake_pid = common_unix_max + 1
+ mapset_tmp_dir_name = Path(self.mapset) / ".tmp" / platform.node()
+ mapset_tmp_dir_name.mkdir(parents=True, exist_ok=True)
+ name = "{}.1".format(fake_pid)
+ fake_tmp_file = mapset_tmp_dir_name / name
+ fake_tmp_file.touch()
+ subprocess.check_call(
+ [self.executable, "--no-clean", self.mapset, "--exec", "g.proj", "-g"]
+ )
+ self.assertTrue(fake_tmp_file.exists(), msg="File should still exist")
+ subprocess.check_call([self.executable, self.mapset, "--exec", "g.proj", "-g"])
+ self.assertFalse(fake_tmp_file.exists(), msg="File should have been deleted")
+
+ def test_cleaning_g_tempfile(self):
+ """Check that --no-clean does not delete existing temp files.
+
+ Then it checks that the file is deleted without --no-clean.
+
+ This makes no assumptions about inner workings of tmp file cleaning,
+ but it relies on g.tempfile to work correctly and that there no
+ other files in the tmp dir.
+ It still needs to assume that there is no process with the PID we used,
+ so clean_temp would delete the file.
+ """
+ common_unix_max = 32768 # common max of unix PIDs
+ fake_pid = common_unix_max + 1
+ mapset_tmp_dir_name = Path(self.mapset) / ".tmp" / platform.node()
+ # we need --no-clean even here otherwise we delete the file at exit
+ subprocess.check_call(
+ [
+ self.executable,
+ self.mapset,
+ "--no-clean",
+ "--exec",
+ "g.tempfile",
+ "pid={}".format(fake_pid),
+ ]
+ )
+ # another process
+ subprocess.check_call(
+ [self.executable, "--no-clean", self.mapset, "--exec", "g.proj", "-g"]
+ )
+ self.assertTrue(
+ os.listdir(str(mapset_tmp_dir_name)), msg="File should still exist"
+ )
+ subprocess.check_call([self.executable, self.mapset, "--exec", "g.proj", "-g"])
+ self.assertFalse(
+ os.listdir(str(mapset_tmp_dir_name)), msg="File should have been deleted"
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/lib/init/testsuite/test_grass_lock.sh b/lib/init/testsuite/test_grass_lock.sh
new file mode 100755
index 00000000000..37f2f02a487
--- /dev/null
+++ b/lib/init/testsuite/test_grass_lock.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+if [[ $# -eq 0 ]]
+then
+ # No arguments supplied, use default which is is small enough to run
+ # well on small machines and does not overwhelm a normal system.
+ NPROC=50
+ ROWS=200
+ COLS=200
+elif [[ $# -eq 3 ]]
+then
+ # Allow user to set a large number of processes.
+ NPROC=$1
+ ROWS=$2
+ COLS=$3
+else
+ >&2 echo "Usage:"
+ >&2 echo " $0"
+ >&2 echo " $0 "
+ >&2 echo "Example which takes a lot of resources:"
+ >&2 echo " $0 1000 500 500"
+ >&2 echo "Use zero or three parameters, not $#"
+ exit 1
+fi
+
+set -e # fail fast
+set -x # repeat commands
+
+GRASS="grass"
+LOCATION="$PWD/test_tmp_mapset_xy"
+MAPSET_PATH="${LOCATION}/PERMANENT"
+
+cleanup () {
+ rm -r "${LOCATION}"
+ exit 1
+}
+
+trap cleanup EXIT
+
+# Setup
+
+"${GRASS}" -e -c XY "${LOCATION}"
+
+"${GRASS}" "${MAPSET_PATH}" --exec g.region rows=$ROWS cols=$COLS
+
+# Test using sleep
+# This shows that --no-lock works.
+
+PARAM="--no-lock"
+# To check that it fails as expected, uncomment the following line.
+# PARAM=""
+
+# Sanity check.
+"${GRASS}" "${MAPSET_PATH}" --exec sleep 1
+
+# Specialized sanity check.
+"${GRASS}" "${MAPSET_PATH}" $PARAM --exec sleep 10 &
+
+for i in `seq 1 ${NPROC}`
+do
+ "${GRASS}" "${MAPSET_PATH}" $PARAM --exec sleep 10 &
+done
+
+wait
+
+# Test with computation
+# When this works, there should be no warnings about "No such file..."
+# Increasing number of processes and size of the region increases chance
+# of warnings and errors, but it is too much to have it in test
+# (1000 processes and rows=10000 cols=10000).
+
+PARAM="--no-clean"
+# To check that it fails as expected, uncomment the following line.
+# PARAM=""
+
+for i in `seq 1 ${NPROC}`
+do
+ "${GRASS}" "${MAPSET_PATH}" --no-lock $PARAM --exec \
+ r.mapcalc "a_$i = sqrt(sin(rand(0, 100)))" -s &
+done
+
+wait
+
+"${GRASS}" "${MAPSET_PATH}" --clean-only
+
+# Evaluate the computation
+# See how many raster maps are in the mapset
+
+EXPECTED="${NPROC}"
+NUM=$("${GRASS}" "${MAPSET_PATH}" --exec g.list type=raster pattern="*" | wc -l)
+
+if [ "$NUM" -ne "$EXPECTED" ]
+then
+ echo "Got $NUM but expected $EXPECTED maps"
+ exit 1
+fi