A multi threading helper library for nushell.
The goal here is not to recreate tokio, but to create smaller-scale helpers like locking and message-channel systems.
numng package name: jan9103/nagoya
.
The documentation is formatted as usage-examples with additional information were needed.
There are 2 implementations for all these:
f
(file-based)- PRO: works as long as all threads have access to a shared directory
- CON: slower due to frequent filesystem interactions
- CON: race conditions are theoretically possible
- concept:
- files are accessible to all threads
"" | save
fails if a file exists making locking possible and moving the responsibility to the filesystem implementation
t
(control thread based)- PRO: faster (zero file I/O)
- PRO: fair FIFO order of request handling instead of "whoever gets lucky"
- CON: no cross nu instance communication
- CON: due to how nu's garbage collection currently works this concept will slowly pollute the RAM
- concept:
- a single threaded nushell job is single threaded
{'sender': (job id), 'tag': $tag, 'request': $request} | job send $server; job recv --tag $tag
can be used like a REST API
A lock, which can be shared across threads.
# import library
use nagoya/t/lock.nu
# or: use nagoya/f/lock.nu
let lock = (lock create)
# wait until the lock is released, and then lock it
lock await $lockfile
do_something
# release the lock
lock unlock $lockfile
# await_lock, run the code, unlock
# but with handling for errors, etc
lock with_lock $lockfile {
do_something
}
A cross-thread queue with locking.
# import library
use nagoya/f/fgq.nu
# or: use nagoya/t/fgq.nu
# create a fgq-que
let que = (fgq create)
fgq push $que {"name": "alice"}
fgq push_all $que [{"name": "bob"}, {"name": "eve"}, {"name": "mallory"}]
let value = (fgq pop $que)
if $value != null { # "pop" returns null if the que is empty
print $"Hello, ($value.name)!"
}
for value in (fgq pop_all $que) {
print $"Hello, ($value.name)!"
}
# delete the que when we no longer need it
fgq delete $que
A data-wrapper, which allows multiple threads to read-write access the same variable safely.
# import library
use nagoya/f/mutex.nu
# or: use nagoya/t/mutex.nu
# create a new mutex with a initial value
let mutex_variable = (mutex new "World")
# change the value
let name = (input "What is your name? ")
mutex set $mutex_variable $name
# change the value while blocking all other access to it between the read and write
mutex change $mutex_variable {|current_value| $current_value | str pascal-case}
# read the current value
print $"Hello, (mutex get $mutex_variable)!"
# clean up and delete the mutex
mutex delete $mutex_variable
scheme: major.minor.patch
:
- patch: non-breaking changes
- fixes for not working things
- new features
- minor: breaking changes to the API
- major: rewrites, or similar drastic changes
recommended version to specify in numng: ~2.0.0