octoleo
/
telegram-bot-bash
mirror of https://github.com/octoleo/telegram-bot-bash.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

doc: improve jsshDB description

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-12-29 11:16:14 +01:00
parent cf6f3eedd7
commit fee0615c28
1 changed files with 14 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/6_reference.md
View File

@ -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