*job_control.txt*    Nvim


		 NVIM REFERENCE MANUAL    by Thiago de Arruda


Nvim job control					*job* *job-control*

Job control is a way to perform multitasking in Nvim, so scripts can spawn and
control multiple processes without blocking the current Nvim instance.

				      Type |gO| to see the table of contents.

==============================================================================
Concepts

Job Id							*job-id*

Each job is identified by an integer id, unique for the life of the current
Nvim session. Each job-id is a valid |channel-id|: they share the same "key
space". Functions like |jobstart()| return job ids; functions like
|jobstop()|, |chansend()|, |rpcnotify()|, and |rpcrequest()| take job ids.

Job stdio streams form a |channel| which can send and receive raw bytes or
|msgpack-rpc| messages.

==============================================================================
Usage							*job-control-usage*

To control jobs, use the "job…" family of functions: |jobstart()|,
|jobstop()|, etc.

Example: >vim

    function! s:OnEvent(job_id, data, event) dict
      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:OnEvent'),
    \ 'on_stderr': function('s:OnEvent'),
    \ 'on_exit': function('s:OnEvent')
    \ }
    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 script, copy it to a file ~/foo.vim and run it: >bash
    nvim -u ~/foo.vim
<
Description of what happens:
  - Two bash shells are spawned by |jobstart()| with their stdin/stdout/stderr
    streams connected to nvim.
  - The first shell is idle, waiting to read commands from its stdin.
  - The second shell is started with -c which executes the command (a for-loop
    printing 0 through 9) and then exits.
  - `OnEvent()` callback is passed to |jobstart()| to handle various job
    events. It displays stdout/stderr data received from the shells.

For |on_stdout| and |on_stderr| see |channel-callback|.
							*on_exit*
Arguments passed to on_exit callback:
  0: |job-id|
  1: Exit-code of the process, or 128+SIGNUM if by signal (e.g. 143 on SIGTERM).
  2: Event type: "exit"


  Note: Buffered stdout/stderr data which has not been flushed