From fee0615c28d31ae089881de406c95c0318b02d4c Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Tue, 29 Dec 2020 11:16:14 +0100 Subject: [PATCH] doc: improve jsshDB description --- doc/6_reference.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/doc/6_reference.md b/doc/6_reference.md index 2270aab..8773f65 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -580,28 +580,25 @@ Usually a message is automatically forwarded from within `commands.sh`, but you ---- ### jsshDB -Since output generated by JSON.sh is so handy to use in bash, we use the format for a simple keys/value file store. -The file extensions is '.jssh' and for security reasons location of jssh files is restricted to BASHBOT_ETC and BASHBOT_DATA.. + +Since output generated by `JSON.sh` is so easy to use in bash, bashbot uses the format for a simple keys/value file store also. #### fast and slow operations -jsshDB files are simple text files and if you append a new Key/value pairs to the end of the file it overwrites -an existing key/value pair. We use this behavior for "fast" file operations. +jsshDB files are text files, key/value pairs appearing later in the file overwrites earlier key/value pairs in the file. +Bashbot use this behavior to implement "fast" file operations. -"fast functions" add a new key/value pair to the end of the file without deleting an existing one, this is fast but over (long) -time the file grows infinity. +"fast functions" add a new key/value pair to the end of a file without deleting an existing one, this is fast but over time the file grows to infinity. -"slow functions" in contrast modify the key/value pairs in place and write the whole file back, -this is slower but clean up the file. All previously added key/value pairs are replaced -and only the last one is written back to the file. +"slow functions" read the file, modify the key/value pairs in memory and write the whole file back, this is slower but removes duplicate keys from the file. -fast functions: +Fast functions: ``` jssh_insertKeyDB , jssh_addKeyDB , jssh_countKeyDB ``` -slow functions: +Slow functions: ``` jssh_writeDB, jssh_updateDB , jssh_deleteKeyDB, jssh_clearDB @@ -610,17 +607,17 @@ slow functions: #### File naming and locking -A jssh fileDB consists of two files which must reside inside `BASHBOT_ETC` or `BASHBOT_DATA`. +A jssh fileDB consists of two files and must reside inside `BASHBOT_ETC` or `BASHBOT_DATA`. -- `filename.jssh` is a text file containing the key/value data in json.sh format. -- `filename.jssh.flock` is used for read/write locking with flock +- `filename.jssh` is the file containing the key/value pairs in json.sh format. +- `filename.jssh.flock` is used to provide read/write locking with flock Path names containing `..` or not located in `BASHBOT_ETC` or `BASHBOT_DATA` are refused by jsshDB functions with an error. -jsshDB functions use file locking with flock, if flock is availible. Write/update operations are serialised to wait until +jsshDB functions use file locking with flock if flock is available. Write/update operations are serialised to wait until previous operations are finished, see "man flock". To avoid deadlocks bashbot use a timeout of 10s for write and 5s for read operations. -For every `jssh_...DB` function a `jsshj_...DB_async` function exsist also. In case don't want locking, use `jssh_...DB_async` functions. +For every `jssh_...DB` function a `jsshj_...DB_async` function exists also. In case don't want locking, use `jssh_...DB_async` functions. *Example:* for allowed file names: ```bash @@ -1149,5 +1146,5 @@ The name of your bot is available as bash variable "$ME", there is no need to ca #### [Prev Best Practice](5_practice.md) #### [Next Notes for Developers](7_develop.md) -#### $$VERSION$$ v1.21-dev-29-g13d15f4 +#### $$VERSION$$ v1.21-dev-30-gcf6f3ee