patch 7.4.1263

Problem:    ch_open() hangs when the server isn't running.
Solution:   Add a timeout. Use a dict to pass arguments. (Yasuhiro Matsumoto)

runtime/doc/channel.txt

@@ -1,4 +1,4 @@
-*channel.txt*      For Vim version 7.4.  Last change: 2016 Feb 04
+*channel.txt*      For Vim version 7.4.  Last change: 2016 Feb 05
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -32,7 +32,7 @@ $VIMRUNTIME/tools/demoserver.py
 Run it in one terminal.  We will call this T1.
 
 Run Vim in another terminal.  Connect to the demo server with: >
-	let handle = ch_open('localhost:8765', 'json')
+	let handle = ch_open('localhost:8765')
 
 In T1 you should see:
 	=== socket opened === ~
@@ -62,23 +62,25 @@ To handle asynchronous communication a callback needs to be used: >
 Instead of giving a callback with every send call, it can also be specified
 when opening the channel: >
 	call ch_close(handle)
-	let handle = ch_open('localhost:8765', 'json', "MyHandler")
+	let handle = ch_open('localhost:8765', {'callback': "MyHandler"})
 	call ch_sendexpr(handle, 'hello!', 0)
 
 ==============================================================================
 2. Opening a channel					*channel-open*
 
 To open a channel: >
-    let handle = ch_open({address}, {mode}, {callback})
+    let handle = ch_open({address} [, {argdict}])
 
 {address} has the form "hostname:port".  E.g., "localhost:8765".
 
-{mode} can be:						*channel-mode*
-	"json" - Use JSON, see below; most convenient way
+{argdict} is a dictionary with optional entries:
+
+"mode" can be:						*channel-mode*
+	"json" - Use JSON, see below; most convenient way. Default.
 	"raw"  - Use raw messages
 
 							*channel-callback*
-{callback} is a function that is called when a message is received that is not
+"callback" is a function that is called when a message is received that is not
 handled otherwise.  It gets two arguments: the channel handle and the received
 message. Example: >
 	func Handle(handle, msg)
@@ -86,16 +88,28 @@ message. Example: >
 	endfunc
 	let handle = ch_open("localhost:8765", 'json', "Handle")
 
-When {mode} is "json" the "msg" argument is the body of the received message,
-converted to Vim types.
-When {mode} is "raw" the "msg" argument is the whole message as a string.
+"waittime" is the time to wait for the connection to be made in milliseconds.
+The default is zero, don't wait, which is useful if the server is supposed to
+be running already.  A negative number waits forever.
 
-When {mode} is "json" the {callback} is optional.  When omitted it is only
+"timeout" is the time to wait for a request when blocking, using
+ch_sendexpr().  Again in millisecons.  The default si 2000 (2 seconds).
+
+When "mode" is "json" the "msg" argument is the body of the received message,
+converted to Vim types.
+When "mode" is "raw" the "msg" argument is the whole message as a string.
+
+When "mode" is "json" the "callback" is optional.  When omitted it is only
 possible to receive a message after sending one.
 
 The handler can be added or changed later: >
     call ch_setcallback(handle, {callback})
-When {callback} is empty (zero or an empty string) the handler is removed.
+When "callback is empty (zero or an empty string) the handler is removed.
+NOT IMPLEMENTED YET
+
+The timeout can be changed later: >
+    call ch_settimeout(handle, {msec})
+NOT IMPLEMENTED YET
 
 Once done with the channel, disconnect it like this: >
     call ch_close(handle)

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 7.4.  Last change: 2016 Feb 04
+*eval.txt*	For Vim version 7.4.  Last change: 2016 Feb 05
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1811,8 +1811,7 @@ call( {func}, {arglist} [, {dict}])
 				any	call {func} with arguments {arglist}
 ceil( {expr})			Float	round {expr} up
 ch_close( {handle})		none	close a channel
-ch_open( {address}, {mode} [, {callback}])
-				Number	open a channel
+ch_open( {address} [, {argdict})] Number open a channel to {address}
 ch_sendexpr( {handle}, {expr} [, {callback}])
 				any	send {expr} over JSON channel {handle}
 ch_sendraw( {handle}, {string} [, {callback}])
@@ -2670,7 +2669,7 @@ confirm({msg} [, {choices} [, {default} [, {type}]]])
 ch_close({handle})					*ch_close()*
 		Close channel {handle}.  See |channel|.
 
-ch_open({address}, {mode} [, {callback}])		*ch_open()*
+ch_open({address} [, {argdict}])				*ch_open()*
 		Open a channel to {address}.  See |channel|.
 		Returns the channel handle on success.  Returns a negative
 		number for failure.
@@ -2678,11 +2677,19 @@ ch_open({address}, {mode} [, {callback}])		*ch_open()*
 		{address} has the form "hostname:port", e.g.,
 		"localhost:8765".
 
-		{mode} is either "json" or "raw".  See |channel-mode| for the
-		meaning.
-
-		{callback} is a function that handles received messages on the
-		channel.  See |channel-callback|.
+		If {argdict} is given it must be a |Directory|.  The optional
+		items are:
+			mode        "raw" or "json".
+				    Default "json".
+			callback    function to call for requests with a zero
+				    sequence number.  See |channel-callback|.
+				    Default: none.
+			waittime    Specify connect timeout as milliseconds.
+				    Negative means forever.
+				    Default: 0.
+			timeout	    Specify response read timeout value as
+				    milliseconds. 
+				    Default: 2000.
 
 ch_sendexpr({handle}, {expr} [, {callback}])		*ch_sendexpr()*
 		Send {expr} over JSON channel {handle}.  See |channel-use|.