mirror of
https://github.com/neovim/neovim.git
synced 2024-12-26 14:11:15 -07:00
e0f66137d1
- Rewrote a few sentences for clarity/brevity
- Various spelling/grammar fixes
- Mention exact time before SIGKILL (mentioned in /src/nvim/os/job.c)
- Reflowed all changed paragraphs accordingly
- Standardize indentation level
- Remove trailing whitespace
- Job control example:
- Don't buffer output (echo -n); just print a new line for every
update.
- Use single quotes around jobsend() arguments to allow for proper
interpretation of newline characters.
- Sleep 1 second between updates instead of 2; 10 seconds is plenty of
time for such a simple example.
102 lines
3.9 KiB
Plaintext
102 lines
3.9 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, and by listening to the |JobActivity|
|
|
event. The best way to understand is with a complete example:
|
|
>
|
|
set nocp
|
|
let job1 = jobstart('shell1', 'bash')
|
|
let job2 = jobstart('shell2', 'bash', ['-c', 'for ((i = 0; i < 10; i++)); do echo hello $i!; sleep 1; done'])
|
|
|
|
function JobHandler()
|
|
if v:job_data[1] == 'stdout'
|
|
let str = 'shell '. v:job_data[0].' stdout: '.join(v:job_data[2])
|
|
elseif v:job_data[1] == 'stderr'
|
|
let str = 'shell '.v:job_data[0].' stderr: '.join(v:job_data[2])
|
|
else
|
|
let str = 'shell '.v:job_data[0].' exited'
|
|
endif
|
|
|
|
call append(line('$'), str)
|
|
endfunction
|
|
|
|
au JobActivity shell* call JobHandler()
|
|
<
|
|
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 called by the `JobActivity` autocommand (notice
|
|
how the shell* pattern matches the names `shell1` and `shell2` passed to
|
|
|jobstart()|), and it takes care of displaying stdout/stderr received from
|
|
the shells.
|
|
- The v:job_data is an array set by the JobActivity event. It has the
|
|
following elements:
|
|
0: The job id
|
|
1: The kind of activity: one of "stdout", "stderr" or "exit"
|
|
2: When "activity" is "stdout" or "stderr", this will contain a list of
|
|
lines read from stdout or stderr
|
|
|
|
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:
|