patch 7.4.1382
Problem: Can't get the job of a channel. Solution: Add ch_getjob().
This commit is contained in:
Bram Moolenaar
@ -1,4 +1,4 @@
|
||||
*channel.txt* For Vim version 7.4. Last change: 2016 Feb 20
|
||||
*channel.txt* For Vim version 7.4. Last change: 2016 Feb 21
|
||||
|
||||
|
||||
VIM REFERENCE MANUAL by Bram Moolenaar
|
||||
@ -93,7 +93,7 @@ To handle asynchronous communication a callback needs to be used: >
|
||||
func MyHandler(channel, msg)
|
||||
echo "from the handler: " . a:msg
|
||||
endfunc
|
||||
call ch_sendexpr(channel, 'hello!', "MyHandler")
|
||||
call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
|
||||
Vim will not wait for a response. Now the server can send the response later
|
||||
and MyHandler will be invoked.
|
||||
|
||||
@ -101,13 +101,15 @@ Instead of giving a callback with every send call, it can also be specified
|
||||
when opening the channel: >
|
||||
call ch_close(channel)
|
||||
let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
|
||||
call ch_sendexpr(channel, 'hello!', 0)
|
||||
call ch_sendexpr(channel, 'hello!', {'callback': 0})
|
||||
|
||||
==============================================================================
|
||||
3. Opening a channel *channel-open*
|
||||
|
||||
To open a channel: >
|
||||
let channel = ch_open({address} [, {options}])
|
||||
if ch_status(channel) == "open"
|
||||
" use the channel
|
||||
|
||||
Use |ch_status()| to see if the channel could be opened.
|
||||
|
||||
@ -131,25 +133,32 @@ Use |ch_status()| to see if the channel could be opened.
|
||||
*channel-callback*
|
||||
"callback" 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: >
|
||||
and the received message. Example: >
|
||||
func Handle(channel, msg)
|
||||
echo 'Received: ' . a:msg
|
||||
endfunc
|
||||
let channel = ch_open("localhost:8765", {"callback": "Handle"})
|
||||
<
|
||||
When "mode" is "json" or "js" the "msg" argument is the body
|
||||
of the received message, converted to Vim types.
|
||||
When "mode" is "nl" the "msg" argument is one message,
|
||||
excluding the NL.
|
||||
When "mode" is "raw" the "msg" argument is the whole message
|
||||
as a string.
|
||||
*out-cb*
|
||||
"out-cb" A function like "callback" but used for stdout. Only for when
|
||||
the channel uses pipes. When "out-cb" wasn't set the channel
|
||||
callback is used.
|
||||
|
||||
*err-cb*
|
||||
"err-cb" A function like "callback" but used for stderr. Only for when
|
||||
the channel uses pipes. When "err-cb" wasn't set the channel
|
||||
callback is used.
|
||||
|
||||
TODO:
|
||||
TODO: *close-cb*
|
||||
"close-cb" A function that is called when the channel gets closed, other
|
||||
than by calling ch_close(). It should be defined like this: >
|
||||
func MyCloseHandler(channel)
|
||||
|
||||
< *waittime*
|
||||
"waittime" 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
|
||||
@ -158,41 +167,34 @@ Use |ch_status()| to see if the channel could be opened.
|
||||
"timeout" The time to wait for a request when blocking, E.g. when using
|
||||
ch_sendexpr(). In milliseconds. The default is 2000 (2
|
||||
seconds).
|
||||
|
||||
*out-timeout* *err-timeout*
|
||||
"out-timeout" Timeout for stdout. Only when using pipes.
|
||||
"err-timeout" Timeout for stderr. Only when using pipes.
|
||||
Note: when setting "timeout" the part specific mode is
|
||||
overwritten. Therefore set "timeout" first and the part
|
||||
specific mode later.
|
||||
|
||||
When "mode" is "json" or "js" 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" or "js" the "callback" is optional. When omitted it is
|
||||
only possible to receive a message after sending one.
|
||||
|
||||
To change the channel options after opening it use ch_setoptions(). The
|
||||
arguments are similar to what is passed to ch_open(), but "waittime" cannot be
|
||||
given, since that only applies to opening the channel.
|
||||
To change the channel options after opening it use |ch_setoptions()|. The
|
||||
arguments are similar to what is passed to |ch_open()|, but "waittime" cannot
|
||||
be given, since that only applies to opening the channel.
|
||||
|
||||
The handler can be added or changed: >
|
||||
For example, the handler can be added or changed: >
|
||||
call ch_setoptions(channel, {'callback': callback})
|
||||
When "callback" is empty (zero or an empty string) the handler is removed.
|
||||
|
||||
The timeout can be changed: >
|
||||
call ch_setoptions(channel, {'timeout': msec})
|
||||
<
|
||||
*E906*
|
||||
*channel-close* *E906*
|
||||
Once done with the channel, disconnect it like this: >
|
||||
call ch_close(channel)
|
||||
When a socket is used this will close the socket for both directions. When
|
||||
pipes are used (stdin/stdout/stderr) they are all closed. This might not be
|
||||
what you want! Stopping the job with job_stop() might be better.
|
||||
|
||||
TODO:
|
||||
Currently up to 10 channels can be in use at the same time. *E897*
|
||||
|
||||
When the channel can't be opened you will get an error message. There is a
|
||||
difference between MS-Windows and Unix: On Unix when the port doesn't exist
|
||||
ch_open() fails quickly. On MS-Windows "waittime" applies.
|
||||
@ -211,12 +213,13 @@ This awaits a response from the other side.
|
||||
When mode is JS this works the same, except that the messages use
|
||||
JavaScript encoding. See |js_encode()| for the difference.
|
||||
|
||||
To send a message, without handling a response: >
|
||||
call ch_sendexpr(channel, {expr}, 0)
|
||||
To send a message, without handling a response or letting the channel callback
|
||||
handle the response: >
|
||||
call ch_sendexpr(channel, {expr}, {'callback': 0})
|
||||
|
||||
To send a message and letting the response handled by a specific function,
|
||||
asynchronously: >
|
||||
call ch_sendexpr(channel, {expr}, {callback})
|
||||
call ch_sendexpr(channel, {expr}, {'callback': Handler})
|
||||
|
||||
Vim will match the response with the request using the message ID. Once the
|
||||
response is received the callback will be invoked. Further responses with the
|
||||
@ -424,13 +427,18 @@ The function will be called with the channel and a message. You would define
|
||||
it like this: >
|
||||
func MyHandler(channel, msg)
|
||||
|
||||
Without the handler you need to read the output with ch_read().
|
||||
Without the handler you need to read the output with |ch_read()| or
|
||||
|ch_readraw()|.
|
||||
|
||||
The handler defined for "out-cb" will also receive stderr. If you want to
|
||||
The handler defined for "out-cb" will not receive stderr. If you want to
|
||||
handle that separately, add an "err-cb" handler: >
|
||||
let job = job_start(command, {"out-cb": "MyHandler",
|
||||
\ "err-cb": "ErrHandler"})
|
||||
|
||||
If you want to handle both stderr and stdout with one handler use the
|
||||
"callback" option: >
|
||||
let job = job_start(command, {"callback": "MyHandler"})
|
||||
|
||||
You can send a message to the command with ch_sendraw(). If the channel is in
|
||||
JSON or JS mode you can use ch_sendexpr().
|
||||
|
||||
@ -481,7 +489,10 @@ This gives the job some time to make the port available.
|
||||
10. Job options *job-options*
|
||||
|
||||
The {options} argument in job_start() is a dictionary. All entries are
|
||||
optional. The same options can be used with job_setoptions(job, {options}).
|
||||
optional. Some options can be used after the job has started, using
|
||||
job_setoptions(job, {options}). Many options can be used with the channel
|
||||
related to the job, using ch_setoptions(channel, {options}).
|
||||
See |job_setoptions()| and |ch_setoptions()|.
|
||||
|
||||
*job-callback*
|
||||
"callback": handler Callback for something to read on any part of the
|
||||
@ -495,13 +506,18 @@ optional. The same options can be used with job_setoptions(job, {options}).
|
||||
TODO: *job-close-cb*
|
||||
"close-cb": handler Callback for when the channel is closed. Same as
|
||||
"close-cb" on ch_open().
|
||||
TODO: *job-exit-cb*
|
||||
*job-exit-cb*
|
||||
"exit-cb": handler Callback for when the job ends. The arguments are the
|
||||
job and the exit status.
|
||||
TODO: *job-killonexit*
|
||||
"killonexit": 1 Stop the job when Vim exits.
|
||||
"killonexit": 0 Do not stop the job when Vim exits.
|
||||
The default is 1.
|
||||
Vim checks about every 10 seconds for jobs that ended.
|
||||
The callback can also be triggered by calling
|
||||
|job_status()|.
|
||||
*job-stoponexit*
|
||||
"stoponexit": {signal} Send {signal} to the job when Vim exits. See
|
||||
|job_stop()| for possible values.
|
||||
"stoponexit": "" Do not stop the job when Vim exits.
|
||||
The default is "term".
|
||||
|
||||
TODO: *job-term*
|
||||
"term": "open" Start a terminal and connect the job
|
||||
stdin/stdout/stderr to it.
|
||||
@ -529,9 +545,6 @@ TODO: *job-err-io*
|
||||
"err-io": "buffer" stderr appends to a buffer
|
||||
"err-buffer": "name" buffer to append to
|
||||
|
||||
TODO: more options
|
||||
|
||||
|
||||
==============================================================================
|
||||
11. Controlling a job *job-control*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user