async.vim

normalize async job control api for vim and neovim

sample usage

function! s:handler(job_id, data, event_type)
    echo a:job_id . ' ' . a:event_type
    echo join(a:data, "\n")
endfunction

if has('win32') || has('win64')
    let argv = ['cmd', '/c', 'dir c:\ /b']
else
    let argv = ['bash', '-c', 'ls']
endif

let jobid = async#job#start(argv, {
    \ 'on_stdout': function('s:handler'),
    \ 'on_stderr': function('s:handler'),
    \ 'on_exit': function('s:handler'),
\ })

if jobid > 0
    echom 'job started'
else
    echom 'job failed to start'
endif

" If you want to get the process id of the job
let pid = async#job#pid(jobid)

" If you want to wait the job:
call async#job#wait([jobid], 5000)  " timeout: 5 sec

" If you want to stop the job:
call async#job#stop(jobid)

APIs

APIs are based on neovim's job control APIs.

• job-control
• jobsend()
• jobstart()
• jobstop()
• jobwait()
• jobpid()

Embedding

Async.vim can be either embedded with other plugins or be used as an external plugin. If you want to embed all you need is to change these 5 function names async#job# to what ever you want. E.g.:

" public apis {{{
function! yourplugin#job#start(cmd, opts) abort
    return s:job_start(a:cmd, a:opts)
endfunction

function! yourplugin#job#stop(jobid) abort
    call s:job_stop(a:jobid)
endfunction

function! yourplugin#job#send(jobid, data) abort
    call s:job_send(a:jobid, a:data)
endfunction

function! yourplugin#job#wait(jobids, ...) abort
    let l:timeout = get(a:000, 0, -1)
    return s:job_wait(a:jobids, l:timeout)
endfunction

function! yourplugin#job#pid(jobid) abort
    return s:job_pid(a:jobid)
endfunction
" }}}

Todos

• Fallback to sync system() calls in vim that doesn't support job
• job_stop and job_send is treated as noop when using system()
• on_stderr doesn't work when using system()
• Fallback to python/ruby threads and vimproc instead of using system() for better compatibility (PRs welcome!!!)