#!/usr/bin/env zsh

#

# zsh-async

#

# version: v1.8.4

# author: Mathias Fredriksson

# url: https://github.com/mafredri/zsh-async

#

typeset -g ASYNC_VERSION=1.8.4

# Produce debug output from zsh-async when set to 1.

typeset -g ASYNC_DEBUG=${ASYNC_DEBUG:-0}

# Execute commands that can manipulate the environment inside the async worker. Return output via callback.

_async_eval() {

}

# Wrapper for jobs executed by the async worker, gives output in parseable format with execution time

_async_job() {

}

# The background worker manages all tasks and runs them without interfering with other processes

_async_worker() {

}

#

# Get results from finished jobs and pass it to the to callback function. This is the only way to reliably return the

# job name, return code, output and execution time and with minimal effort.

#

# If the async process buffer becomes corrupt, the callback will be invoked with the first argument being `[async]` (job

# name), non-zero return code and fifth argument describing the error (stderr).

#

# usage:

# async_process_results <worker_name> <callback_function>

#

# callback_function is called with the following parameters:

# $1 = job name, e.g. the function passed to async_job

# $2 = return code

# $3 = resulting stdout from execution

# $4 = execution time, floating point e.g. 2.05 seconds

# $5 = resulting stderr from execution

# $6 = has next result in buffer (0 = buffer empty, 1 = yes)

#

async_process_results() {

setopt localoptions unset noshwordsplit noksharrays noposixidentifiers noposixstrings

local worker=$1

local callback=$2

local caller=$3

local -a items

local null=$'\0' data

integer -l len pos num_processed has_next

typeset -gA ASYNC_PROCESS_BUFFER

# Read output from zpty and parse it if available.

while zpty -r -t $worker data 2>/dev/null; do

ASYNC_PROCESS_BUFFER[$worker]+=$data

len=${#ASYNC_PROCESS_BUFFER[$worker]}

pos=${ASYNC_PROCESS_BUFFER[$worker][(i)$null]} # Get index of NULL-character (delimiter).

# Keep going until we find a NULL-character.

if (( ! len )) || (( pos > len )); then

continue

fi

while (( pos <= len )); do

# Take the content from the beginning, until the NULL-character and

# perform shell parsing (z) and unquoting (Q) as an array (@).

items=("${(@Q)${(z)ASYNC_PROCESS_BUFFER[$worker][1,$pos-1]}}")

# Remove the extracted items from the buffer.

ASYNC_PROCESS_BUFFER[$worker]=${ASYNC_PROCESS_BUFFER[$worker][$pos+1,$len]}

len=${#ASYNC_PROCESS_BUFFER[$worker]}

if (( len > 1 )); then

pos=${ASYNC_PROCESS_BUFFER[$worker][(i)$null]} # Get index of NULL-character (delimiter).

fi

has_next=$(( len != 0 ))

if (( $#items == 5 )); then

items+=($has_next)

$callback "${(@)items}" # Send all parsed items to the callback.

(( num_processed++ ))

elif [[ -z $items ]]; then

# Empty items occur between results due to double-null ($'\0\0')

# caused by commands being both pre and suffixed with null.

else

# In case of corrupt data, invoke callback with *async* as job

# name, non-zero exit status and an error message on stderr.

$callback "[async]" 1 "" 0 "$0:$LINENO: error: bad format, got ${#items} items (${(q)items})" $has_next

fi

done

done

(( num_processed )) && return 0

# Avoid printing exit value when `setopt printexitvalue` is active.`

[[ $caller = trap || $caller = watcher ]] && return 0

# No results were processed

return 1

}

# Watch worker for output

_async_zle_watcher() {

}

_async_send_job() {

}

#

# Start a new asynchronous job on specified worker, assumes the worker is running.

#

# usage:

# async_job <worker_name> <my_function> [<function_params>]

#

async_job() {

}

#

# Evaluate a command (like async_job) inside the async worker, then worker environment can be manipulated. For example,

# issuing a cd command will change the PWD of the worker which will then be inherited by all future async jobs.

#

# Output will be returned via callback, job name will be [async/eval].

#

# usage:

# async_worker_eval <worker_name> <my_function> [<function_params>]

#

async_worker_eval() {

}

# This function traps notification signals and calls all registered callbacks

_async_notify_trap() {

}

#

# Register a callback for completed jobs. As soon as a job is finnished, async_process_results will be called with the

# specified callback function. This requires that a worker is initialized with the -n (notify) option.

#

# usage:

# async_register_callback <worker_name> <callback_function>

#

async_register_callback() {

}

#

# Unregister the callback for a specific worker.

#

# usage:

# async_unregister_callback <worker_name>

#

async_unregister_callback() {

}

#

# Flush all current jobs running on a worker. This will terminate any and all running processes under the worker, use

# with caution.

#

# usage:

# async_flush_jobs <worker_name>

#

async_flush_jobs() {

setopt localoptions noshwordsplit

local worker=$1; shift

# Check if the worker exists

zpty -t $worker &>/dev/null || return 1

# Send kill command to worker

async_job $worker "_killjobs"

# Clear the zpty buffer.

local junk

if zpty -r -t $worker junk '*'; then

(( ASYNC_DEBUG )) && print -n "async_flush_jobs $worker: ${(V)junk}"

while zpty -r -t $worker junk '*'; do

(( ASYNC_DEBUG )) && print -n "${(V)junk}"

done

(( ASYNC_DEBUG )) && print

fi

# Finally, clear the process buffer in case of partially parsed responses.

typeset -gA ASYNC_PROCESS_BUFFER

unset "ASYNC_PROCESS_BUFFER[$worker]"

}

#

# Start a new async worker with optional parameters, a worker can be told to only run unique tasks and to notify a

# process when tasks are complete.

#

# usage:

# async_start_worker <worker_name> [-u] [-n] [-p <pid>]

#

# opts:

# -u unique (only unique job names can run)

# -n notify through SIGWINCH signal

# -p pid to notify (defaults to current pid)

#

async_start_worker() {

setopt localoptions noshwordsplit noclobber

local worker=$1; shift

local -a args

args=("$@")

zpty -t $worker &>/dev/null && return

typeset -gA ASYNC_PTYS

typeset -h REPLY

typeset has_xtrace=0

if [[ -o interactive ]] && [[ -o zle ]]; then

# Inform the worker to ignore the notify flag and that we're

# using a ZLE watcher instead.

args+=(-z)

if (( ! ASYNC_ZPTY_RETURNS_FD )); then

# When zpty doesn't return a file descriptor (on older versions of zsh)

# we try to guess it anyway.

integer -l zptyfd

exec {zptyfd}>&1 # Open a new file descriptor (above 10).

exec {zptyfd}>&- # Close it so it's free to be used by zpty.

fi

fi

# Workaround for stderr in the main shell sometimes (incorrectly) being

# reassigned to /dev/null by the reassignment done inside the async

# worker.

# See https://github.com/mafredri/zsh-async/issues/35.

integer errfd=-1

exec {errfd}>&2

# Make sure async worker is started without xtrace

# (the trace output interferes with the worker).

[[ -o xtrace ]] && {

has_xtrace=1

unsetopt xtrace

}

zpty -b $worker _async_worker -p $$ $args 2>&$errfd

local ret=$?

# Re-enable it if it was enabled, for debugging.

(( has_xtrace )) && setopt xtrace

exec {errfd}>& -

if (( ret )); then

async_stop_worker $worker

return 1

fi

if ! is-at-least 5.0.8; then

# For ZSH versions older than 5.0.8 we delay a bit to give

# time for the worker to start before issuing commands,

# otherwise it will not be ready to receive them.

sleep 0.001

fi

if [[ -o interactive ]] && [[ -o zle ]]; then

if (( ! ASYNC_ZPTY_RETURNS_FD )); then

REPLY=$zptyfd # Use the guessed value for the file desciptor.

fi

ASYNC_PTYS[$REPLY]=$worker # Map the file desciptor to the worker.

fi

}

#

# Stop one or multiple workers that are running, all unfetched and incomplete work will be lost.

#

# usage:

# async_stop_worker <worker_name_1> [<worker_name_2>]

#

async_stop_worker() {

setopt localoptions noshwordsplit

local ret=0 worker k v

for worker in $@; do

# Find and unregister the zle handler for the worker

for k v in ${(@kv)ASYNC_PTYS}; do

if [[ $v == $worker ]]; then

zle -F $k

unset "ASYNC_PTYS[$k]"

fi

done

async_unregister_callback $worker

zpty -d $worker 2>/dev/null || ret=$?

# Clear any partial buffers.

typeset -gA ASYNC_PROCESS_BUFFER

unset "ASYNC_PROCESS_BUFFER[$worker]"

done

return $ret

}

#

# Initialize the required modules for zsh-async. To be called before using the zsh-async library.

#

# usage:

# async_init

#

async_init() {

}

async() {

async_init

}

async "$@"