runtime: Initial job control documentation

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:

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.

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: