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)
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 31b55cd..0bc98f1 100644
--- a/runtime/doc/channel.txt
+++ b/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 @@
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 @@
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 @@
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)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 49b7b0f..c812d0a 100644
--- a/runtime/doc/eval.txt
+++ b/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 @@
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 @@
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 @@
{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|.