From a7997f21b5b7a1b934231ff31f3e50a60511f097 Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Wed, 27 May 2020 10:57:25 +0200 Subject: [PATCH] update jsshdb doc --- doc/6_reference.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/doc/6_reference.md b/doc/6_reference.md index 15bc332..421c53f 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -466,9 +466,41 @@ Since output generated by JSON.sh is so handy to use in bash, we use the format fucntions to read and write JSON.sh style data from and to files. The file extions is '.jssh' and for security reasons location of jssh files is restricted to BASHBOT_ETC and BASHBOT_DATA.. -Note: File names containg '..' and absolute file names pointing outside BASHBOT_ETC or BASHBOT_DATA are refused by jsshDB functions. +#### fast and slow database operations -Note2: Since version 0.94 jsshDB functions support file locking with flock. Write / Update operations use flock to wait until +jsshDB files are simple text files and you can add new Key/value pairs at the end of the file, this overwritesn +already existing key/value pairs with new values. + +Funtions simply add to the end without deleting an existing key/value pair are fast, but over time the +file grows with every write. I call this funtions "fast functions". + +"slow funtions" in contrast read the whole file, modify the key/value pairs and write the whole file back. +this needs more time and IO, but does clean up the file. All duplicate added key/value pairs are deleted +and only the last valid value is written to the file. + +fast functions: + +``` + jssh_insertDB , jssh_addKeyDB , jssh_countKeyDB +``` + +slow functions: + +``` + jssh_writeDB, jssh_updateDB , jssh_deleteKeyDBB +``` + + +#### File nameing and locking + +A jssh fileDB consists of maximum two files witch must reside inside BASHBOT_ETC or BASHBOT_DATA. + +- `filename.jssh` is a text file containing the data in the format as json.sh outputs. +- optional file `filename.jssh.flock` used for read/write locking with flock + +Path names names containing '..' and absolute path names pointing outside BASHBOT_ETC or BASHBOT_DATA are refused by jsshDB functions. + +Since version 0.94 jsshDB functions support file locking with flock. Write / Update operations use flock to wait until previous operations are finished. see "man flock" for more information. Bashbot uses a maximum timeout of 10 seconds for flock. If you don't want atomic write / update operations use the *_async variant of jsshDB functions. If flock is not availible @@ -989,5 +1021,5 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca #### [Prev Best Practice](5_practice.md) #### [Next Notes for Developers](7_develop.md) -#### $$VERSION$$ v0.96-dev-7-g0153928 +#### $$VERSION$$ 0.96-dev2-1-g67b9039