diff options
| -rw-r--r-- | runtime/doc/autocmd.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 20 | ||||
| -rw-r--r-- | runtime/doc/job_control.txt | 101 |
3 files changed, 127 insertions, 1 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 2a8becebff..8f70279310 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -303,6 +303,7 @@ Name triggered by ~ |InsertLeave| when leaving Insert mode |InsertCharPre| when a character was typed in Insert mode, before inserting it +|JobActivity| when something interesting happen with a job |TextChanged| after a change was made to the text in Normal mode |TextChangedI| after a change was made to the text in Insert mode @@ -712,6 +713,10 @@ InsertEnter Just before starting Insert mode. Also for *InsertLeave* InsertLeave When leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. + {Nvim} *JobActivity* +JobActivity When something interesting happens with a job + spawned by |jobstart()|. See |job-control| for + details. *MenuPopup* MenuPopup Just before showing the popup menu (under the right mouse button). Useful for adjusting the @@ -1383,4 +1388,4 @@ This will write the file without triggering the autocommands defined by the gzip plugin. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 51e09596fc..bbd43f9b9a 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1865,6 +1865,10 @@ invert( {expr}) Number bitwise invert isdirectory( {directory}) Number TRUE if {directory} is a directory islocked( {expr}) Number TRUE if {expr} is locked items( {dict}) List key-value pairs in {dict} +job_close({job}) Closes a job with id {job} +job_send({job}, {data}) Writes {data} to {job}'s stdin +job_spawn({name}, {prog}[, {argv}]) + Spawns {prog} as a job associated with {name} join( {list} [, {sep}]) String join {list} items into one String keys( {dict}) List keys in {dict} len( {expr}) Number the length of {expr} @@ -4008,6 +4012,22 @@ items({dict}) *items()* entry and the value of this entry. The |List| is in arbitrary order. +jobsend({job}, {data}) {Nvim} *jobsend()* + Send data to {job} by writing it to the stdin of the process. + See |job-control| for more information. + +jobstart({name}, {prog}[, {argv}]) {Nvim} *jobstart()* + Spawns {prog} as a job and associate it with the {name} string, + which will be used to match the "filename pattern" in + |JobActivity| events. See |job-control| for more information. + +jobstop({job}) {Nvim} *jobstop()* + Stop a job created with |jobstart| by sending a `SIGTERM` + to the corresponding process. If the process doesn't exit + cleanly soon, a `SIGKILL` will be sent. When the job is + finally closed, a |JobActivity| event will trigger with + `v:job_data[0]` set to `exited`. See |job-control| for more + information. join({list} [, {sep}]) *join()* Join the items in {list} together into one String. diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt new file mode 100644 index 0000000000..c76b4f460b --- /dev/null +++ b/runtime/doc/job_control.txt @@ -0,0 +1,101 @@ +*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 installed shells, calling OS functions for process management directly. + +Internally, Nvim job control is powered by libuv, which has a nice +cross-platform API for managing processes. See https://github.com/joyent/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 -n hello $i!; sleep 2; done']) + + function JobHandler() + if v:job_data[1] == 'stdout' + let str = 'shell '. v:job_data[0].' stdout: '.v:job_data[2] + elseif v:job_data[1] == 'stderr' + let str = 'shell '.v:job_data[0].' stderr: '.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 ~/jobcontrol.vim file and start with a clean +nvim instance: + > + nvim -u NONE -S ~/jobcontrol.vim +< +Here's what is happening: + +- Two bash instances are spawned |jobstart()| and their stdin/stdout/stderr + are connected to nvim. +- The first shell is idle, waiting to read commands from it's stdin +- The second shell is passed the -c option to execute a command and exit. In + our case, the command is a for loop that will print numbers and exit after + a while. +- The JobHandler function is called by the JobActivity autocommand(notice how + it the shell* pattern matches the `shell1` and `shell2` names 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 the data 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')<cr> + :call jobsend(job1, 'invalid-command\n')<cr> + :call jobsend(job1, 'exit\n')<cr> +< +A job may be killed at any time with the |jobstop()| function: +> + :call jobstop(job1) +< +When |jobstop()| is called, it will send `SIGTERM` to the job. If a job +doesn't exit after a while, `SIGKILL` will be sent. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: |