prepare map

Start a transaction made up of multiple map file changes.

Description Jump to heading #

If you need to make multiple changes to a map file, and you need them to be applied all at the same time in one atomic change, submit them in a transaction using the prepare map and commit map commands.

• Use prepare map to initiate the transaction.
• Use add map and clear map as needed to make map changes.
• Use show map to review the temporary version.
• Use commit map to commit the changes and make them active in runtime memory.

The prepare map command starts the transaction by allocating a new version number for a map ID or filename returned by show map. The map ID or filename argument is passed to the prepare map command. The command responds with the new version number in the New version created: statement.

You can use the version number in the add map, clear map, and show map commands.

There is no impact of allocating new versions, as unused versions will automatically be removed once a more recent version is committed. Version numbers are unsigned 32-bit values which wrap at the end, so care must be taken when comparing them in an external program.

The prepare map operation creates an empty version of the map. Consequently, committing the version without first adding any entries effectively clears the map in runtime memory.

There is no abort map command. To abandon a transaction, simply do not commit it. Any uncommitted transaction is removed the next time you execute the prepare map command.

Examples Jump to heading #

1. Use the show maps command to list map files and their unique IDs.

   nix
   echo "show map" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show map" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   # id (file) description
   0 (/etc/hapee-2.8/routes.map) pattern loaded from file '/etc/hapee-2.8/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 61. curr_ver=0 next_ver=1 entry_cnt=0

   output
   text
   # id (file) description
   0 (/etc/hapee-2.8/routes.map) pattern loaded from file '/etc/hapee-2.8/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 61. curr_ver=0 next_ver=1 entry_cnt=0

2. Pass the map file’s unique ID to show map to display entries in the file:

   nix
   echo "show map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   0x563bbeeee160 /cart/ cart_api
   0x563bbeeee1a0 /reviews/ reviews_api

   output
   text
   0x563bbeeee160 /cart/ cart_api
   0x563bbeeee1a0 /reviews/ reviews_api

3. Use prepare map to start a transaction.

   nix
   echo "prepare map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "prepare map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   New version created: 1

   output
   text
   New version created: 1

4. Delete all keys and values from the temporary transaction file.

   nix
   echo "clear map @1 #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "clear map @1 #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

5. Use commit map to apply the transaction.

   nix
   echo "commit map @1 #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "commit map @1 #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

See also Jump to heading #

• add map
• clear map
• commit map
• del map
• get map
• set map
• show map