Skip to content

Jan9103/nagoya

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Nagoya

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.

Documentation

The documentation is formatted as usage-examples with additional information were needed.

Implementations

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

Lock

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
}

FGQ: Fifo Global Queue

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

Mutex

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

Versions

changelog

Version system

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

About

A multithreading helper library for nushell

Topics

Resources

License

Stars

Watchers

Forks