mirror of
https://github.com/neovim/neovim.git
synced 2024-12-26 14:11:15 -07:00
6e7757ad51
- Remove JobActivity autocmd and v:job_data variable
- Simplify `jobstart` to receive:
- An argument vector
- An optional dictionary which may contain any of the current `jobstart`
options plus `on_stdout`, `on_stderr` and `on_exit` callbacks.
- Refactor and add more job tests
- Update documentation
138 lines
4.8 KiB
Plaintext
138 lines
4.8 KiB
Plaintext
*job_control.txt* For Nvim. {Nvim}
|
|
|
|
|
|
NVIM REFERENCE MANUAL by Thiago de Arruda
|
|
|
|
|
|
Nvim's facilities for job control *job-control*
|
|
|
|
1. Introduction |job-control-intro|
|
|
2. Usage |job-control-usage|
|
|
|
|
==============================================================================
|
|
1. Introduction *job-control-intro*
|
|
|
|
Job control is a simple way to perform multitasking in vimscript. Wikipedia
|
|
contains a more generic/detailed description:
|
|
|
|
"Job control in computing refers to the control of multiple tasks or Jobs on a
|
|
computer system, ensuring that they each have access to adequate resources to
|
|
perform correctly, that competition for limited resources does not cause a
|
|
deadlock where two or more jobs are unable to complete, resolving such
|
|
situations where they do occur, and terminating jobs that, for any reason, are
|
|
not performing as expected."
|
|
|
|
In a few words: It allows a vimscript programmer to concurrently spawn and
|
|
control multiple processes without blocking the current Nvim instance.
|
|
|
|
Nvim's job control was designed to be simple and familiar to vimscript
|
|
programmers, instead of being very powerful but complex. Unlike Vim's
|
|
facilities for calling with external commands, job control does not depend on
|
|
available shells, instead relying on OS functionality for process management.
|
|
|
|
Internally, Nvim job control is powered by libuv, which has a nice
|
|
cross-platform API for managing processes. See https://github.com/libuv/libuv
|
|
for details
|
|
|
|
==============================================================================
|
|
2. Usage *job-control-usage*
|
|
|
|
Job control is achieved by calling a combination of the |jobstart()|,
|
|
|jobsend()| and |jobstop()| functions. Here's an example:
|
|
>
|
|
function s:JobHandler(job_id, data, event)
|
|
if a:event == 'stdout'
|
|
let str = self.shell.' stdout: '.join(a:data)
|
|
elseif a:event == 'stderr'
|
|
let str = self.shell.' stderr: '.join(a:data)
|
|
else
|
|
let str = self.shell.' exited'
|
|
endif
|
|
|
|
call append(line('$'), str)
|
|
endfunction
|
|
let s:callbacks = {
|
|
\ 'on_stdout': function('s:JobHandler'),
|
|
\ 'on_stderr': function('s:JobHandler'),
|
|
\ 'on_exit': function('s:JobHandler')
|
|
\ }
|
|
let job1 = jobstart(['bash'], extend({'shell': 'shell 1'}, s:callbacks))
|
|
let job2 = jobstart(['bash', '-c', 'for i in {1..10}; do echo hello $i!; sleep 1; done'], extend({'shell': 'shell 2'}, s:callbacks))
|
|
|
|
<
|
|
To test the above, copy it to the file ~/jobcontrol.vim and start with a clean
|
|
nvim instance:
|
|
>
|
|
nvim -u NONE -S ~/jobcontrol.vim
|
|
<
|
|
Here's what is happening:
|
|
|
|
- Two bash instances are spawned by |jobstart()| with their stdin/stdout/stderr
|
|
connected to nvim.
|
|
- The first shell is idle, waiting to read commands from its stdin.
|
|
- The second shell is started with the -c argument, causing it to execute a
|
|
command then exit. In this case, the command is a for loop that will print 0
|
|
through 9 then exit.
|
|
- The `JobHandler()` function is a callback passed to |jobstart()| to handle
|
|
various job events. It takes care of displaying stdout/stderr received from
|
|
the shells.
|
|
- The arguments passed to `JobHandler()` are:
|
|
|
|
0: The job id
|
|
1: If the event is "stdout" or "stderr", a list with lines read from the
|
|
corresponding stream. For "exit", it is the status returned by the
|
|
program.
|
|
2: The event type, which is "stdout", "stderr" or "exit".
|
|
|
|
The options dictionary is passed as the "self" variable to the callback
|
|
function. Here's a more object-oriented version of the above:
|
|
>
|
|
let Shell = {}
|
|
|
|
function Shell.on_stdout(job_id, data)
|
|
call append(line('$'), self.get_name().' stdout: '.join(a:data))
|
|
endfunction
|
|
|
|
function Shell.on_stderr(job_id, data)
|
|
call append(line('$'), self.get_name().' stderr: '.join(a:data))
|
|
endfunction
|
|
|
|
function Shell.on_exit(job_id, data)
|
|
call append(line('$'), self.get_name().' exited')
|
|
endfunction
|
|
|
|
function Shell.get_name()
|
|
return 'shell '.self.name
|
|
endfunction
|
|
|
|
function Shell.new(name, ...)
|
|
let instance = extend(copy(g:Shell), {'name': a:name})
|
|
let argv = ['bash']
|
|
if a:0 > 0
|
|
let argv += ['-c', a:1]
|
|
endif
|
|
let instance.id = jobstart(argv, instance)
|
|
return instance
|
|
endfunction
|
|
|
|
let s1 = Shell.new('1')
|
|
let s2 = Shell.new('2', 'for i in {1..10}; do echo hello $i!; sleep 1; done')
|
|
|
|
|
|
To send data to the job's stdin, one can use the |jobsend()| function, like
|
|
this:
|
|
>
|
|
:call jobsend(job1, "ls\n")
|
|
:call jobsend(job1, "invalid-command\n")
|
|
:call jobsend(job1, "exit\n")
|
|
<
|
|
A job may be killed at any time with the |jobstop()| function:
|
|
>
|
|
:call jobstop(job1)
|
|
<
|
|
When |jobstop()| is called, `SIGTERM` will be sent to the job. If a job does
|
|
not exit after 2 seconds, `SIGKILL` will be sent.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|