Mercurial > vim

comparison runtime/doc/channel.txt @ 8061:abd64cf67bcf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Feb 15 22:07:32 2016 +0100 Update runtime files.
author Christian Brabandt <cb@256bit.org>
date Mon, 15 Feb 2016 22:45:05 +0100
parents 78106b0f2c56
children 18a3f0f05244
comparison
equal deleted inserted replaced
8060:ec3056fe30fd 8061:abd64cf67bcf
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 07 1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 15
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
7 Inter-process communication *channel* 7 Inter-process communication *channel*
8 8
9 DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT 9 DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
10 10
11 Vim uses channels to communicate with other processes. 11 Vim uses channels to communicate with other processes.
12 A channel uses a socket. *socket-interface* 12 A channel uses a socket or pipes *socket-interface*
13 Jobs can be used to start processes and communicate with them.
13 14
14 Vim current supports up to 10 simultaneous channels. 15 Vim current supports up to 10 simultaneous channels.
15 The Netbeans interface also uses a channel. |netbeans| 16 The Netbeans interface also uses a channel. |netbeans|
16 17
17 1. Demo |channel-demo| 18 1. Overview |job-channel-overview|
18 2. Opening a channel |channel-open| 19 2. Channel demo |channel-demo|
19 3. Using a JSON or JS channel |channel-use| 20 3. Opening a channel |channel-open|
20 4. Vim commands |channel-commands| 21 4. Using a JSON or JS channel |channel-use|
21 5. Using a raw channel |channel-use| 22 5. Channel commands |channel-commands|
22 6. Job control |job-control| 23 6. Using a RAW or NL channel |channel-raw|
24 7. More channel functions |channel-more|
25 8. Starting a job with a channel |job-start|
26 9. Starting a job without a channel |job-start-nochannel|
27 10. Job options |job-options|
28 11. Controlling a job |job-control|
23 29
24 {Vi does not have any of these features} 30 {Vi does not have any of these features}
25 {only available when compiled with the |+channel| feature} 31 {only when compiled with the |+channel| feature for channel stuff}
26 32 {only when compiled with the |+job| feature for job stuff}
27 ============================================================================== 33
28 1. Demo *channel-demo* 34 ==============================================================================
35 1. Overview *job-channel-overview*
36
37 There are four main types of jobs:
38 1. A deamon, serving several Vim instances.
39 Vim connects to it with a socket.
40 2. One job working with one Vim instance, asynchronously.
41 Uses a socket or pipes.
42 3. A job performing some work for a short time, asynchronously.
43 Uses a socket or pipes.
44 4. Running a filter, synchronously.
45 Uses pipes.
46
47 For when using sockets See |job-start|, |job-may-start| and |channel-open|.
48 For 2 and 3, one or more jobs using pipes, see |job-start|.
49 For 4 use the ":{range}!cmd" command, see |filter|.
50
51 Over the socket and pipes these protocols are available:
52 RAW nothing known, Vim cannot tell where a message ends
53 NL every message ends in a NL (newline) character
54 JSON JSON encoding |json_encode()|
55 JS JavaScript style JSON-like encoding |js_encode()|
56
57 Common combination are:
58 - Using a job connected through pipes in NL mode. E.g., to run a style
59 checker and receive errors and warnings.
60 - Using a deamon, connecting over a socket in JSON mode. E.g. to lookup
61 crosss-refrences in a database.
62
63 ==============================================================================
64 2. Channel demo *channel-demo*
29 65
30 This requires Python. The demo program can be found in 66 This requires Python. The demo program can be found in
31 $VIMRUNTIME/tools/demoserver.py 67 $VIMRUNTIME/tools/demoserver.py
32 Run it in one terminal. We will call this T1. 68 Run it in one terminal. We will call this T1.
33 69
34 Run Vim in another terminal. Connect to the demo server with: > 70 Run Vim in another terminal. Connect to the demo server with: >
35 let handle = ch_open('localhost:8765') 71 let channel = ch_open('localhost:8765')
36 72
37 In T1 you should see: 73 In T1 you should see:
38 === socket opened === ~ 74 === socket opened === ~
39 75
40 You can now send a message to the server: > 76 You can now send a message to the server: >
41 echo ch_sendexpr(handle, 'hello!') 77 echo ch_sendexpr(channel, 'hello!')
42 78
43 The message is received in T1 and a response is sent back to Vim. 79 The message is received in T1 and a response is sent back to Vim.
44 You can see the raw messages in T1. What Vim sends is: 80 You can see the raw messages in T1. What Vim sends is:
45 [1,"hello!"] ~ 81 [1,"hello!"] ~
46 And the response is: 82 And the response is:
52 ["ex","echo 'hi there'"] ~ 88 ["ex","echo 'hi there'"] ~
53 And you should see the message in Vim. You can move the cursor a word forward: 89 And you should see the message in Vim. You can move the cursor a word forward:
54 ["normal","w"] ~ 90 ["normal","w"] ~
55 91
56 To handle asynchronous communication a callback needs to be used: > 92 To handle asynchronous communication a callback needs to be used: >
57 func MyHandler(handle, msg) 93 func MyHandler(channel, msg)
58 echo "from the handler: " . a:msg 94 echo "from the handler: " . a:msg
59 endfunc 95 endfunc
60 call ch_sendexpr(handle, 'hello!', "MyHandler") 96 call ch_sendexpr(channel, 'hello!', "MyHandler")
97 Vim will not wait for a response. Now the server can send the response later
98 and MyHandler will be invoked.
61 99
62 Instead of giving a callback with every send call, it can also be specified 100 Instead of giving a callback with every send call, it can also be specified
63 when opening the channel: > 101 when opening the channel: >
64 call ch_close(handle) 102 call ch_close(channel)
65 let handle = ch_open('localhost:8765', {'callback': "MyHandler"}) 103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
66 call ch_sendexpr(handle, 'hello!', 0) 104 call ch_sendexpr(channel, 'hello!', 0)
67 105
68 ============================================================================== 106 ==============================================================================
69 2. Opening a channel *channel-open* 107 3. Opening a channel *channel-open*
70 108
71 To open a channel: > 109 To open a channel: >
72 let handle = ch_open({address} [, {argdict}]) 110 let channel = ch_open({address} [, {options}])
111
112 Use |ch_status()| to see if the channel could be opened.
73 113
74 {address} has the form "hostname:port". E.g., "localhost:8765". 114 {address} has the form "hostname:port". E.g., "localhost:8765".
75 115
76 {argdict} is a dictionary with optional entries: 116 {options} is a dictionary with optional entries:
77 117
78 "mode" can be: *channel-mode* 118 "mode" can be: *channel-mode*
79 "json" - Use JSON, see below; most convenient way. Default. 119 "json" - Use JSON, see below; most convenient way. Default.
80 "js" - Use JavaScript encoding, more efficient than JSON. 120 "js" - Use JavaScript encoding, more efficient than JSON.
121 "nl" - Use messages that end in a NL character
81 "raw" - Use raw messages 122 "raw" - Use raw messages
82 123
83 *channel-callback* 124 *channel-callback*
84 "callback" is a function that is called when a message is received that is not 125 "callback" A function that is called when a message is received that is
85 handled otherwise. It gets two arguments: the channel handle and the received 126 not handled otherwise. It gets two arguments: the channel
86 message. Example: > 127 handle and the received message. Example: >
87 func Handle(handle, msg) 128 func Handle(channel, msg)
88 echo 'Received: ' . a:msg 129 echo 'Received: ' . a:msg
89 endfunc 130 endfunc
90 let handle = ch_open("localhost:8765", {"callback": "Handle"}) 131 let channel = ch_open("localhost:8765", {"callback": "Handle"})
91 132 <
92 "waittime" is the time to wait for the connection to be made in milliseconds. 133 TODO:
93 The default is zero, don't wait, which is useful if the server is supposed to 134 "err-cb" A function like "callback" but used for stderr. Only for when
94 be running already. A negative number waits forever. 135 the channel uses pipes.
95 136
96 "timeout" is the time to wait for a request when blocking, using 137 TODO:
97 ch_sendexpr(). Again in milliseconds. The default is 2000 (2 seconds). 138 "close-cb" A function that is called when the channel gets closed, other
139 than by calling ch_close(). It should be defined like this: >
140 func MyCloseHandler(channel)
141
142 "waittime" The time to wait for the connection to be made in
143 milliseconds. The default is zero, don't wait, which is
144 useful if the server is supposed to be running already. A
145 negative number waits forever.
146
147 "timeout" The time to wait for a request when blocking, using
148 ch_sendexpr(). Again in milliseconds. The default is 2000 (2
149 seconds).
98 150
99 When "mode" is "json" or "js" the "msg" argument is the body of the received 151 When "mode" is "json" or "js" the "msg" argument is the body of the received
100 message, converted to Vim types. 152 message, converted to Vim types.
101 When "mode" is "raw" the "msg" argument is the whole message as a string. 153 When "mode" is "raw" the "msg" argument is the whole message as a string.
102 154
103 When "mode" is "json" or "js" the "callback" is optional. When omitted it is 155 When "mode" is "json" or "js" the "callback" is optional. When omitted it is
104 only possible to receive a message after sending one. 156 only possible to receive a message after sending one.
105 157
106 The handler can be added or changed later: > 158 TODO:
107 call ch_setcallback(handle, {callback}) 159 To change the channel options after opening it use ch_setoptions(). The
160 arguments are similar to what is passed to ch_open(), but "waittime" cannot be
161 given, since that only applies to opening the channel.
162
163 The handler can be added or changed: >
164 call ch_setoptions(channel, {'callback': callback})
108 When "callback" is empty (zero or an empty string) the handler is removed. 165 When "callback" is empty (zero or an empty string) the handler is removed.
109 NOT IMPLEMENTED YET 166
110 167 The timeout can be changed: >
111 The timeout can be changed later: > 168 call ch_setoptions(channel, {'timeout': msec})
112 call ch_settimeout(handle, {msec}) 169 <
113 NOT IMPLEMENTED YET
114 *E906* 170 *E906*
115 Once done with the channel, disconnect it like this: > 171 Once done with the channel, disconnect it like this: >
116 call ch_close(handle) 172 call ch_close(channel)
117 173 When a socket is used this will close the socket for both directions. When
174 pipes are used (stdin/stdout/stderr) they are all closed. This might not be
175 what you want! Stopping the job with job_stop() might be better.
176
177 TODO:
118 Currently up to 10 channels can be in use at the same time. *E897* 178 Currently up to 10 channels can be in use at the same time. *E897*
119 179
120 When the channel can't be opened you will get an error message. There is a 180 When the channel can't be opened you will get an error message. There is a
121 difference between MS-Windows and Unix: On Unix when the port doesn't exist 181 difference between MS-Windows and Unix: On Unix when the port doesn't exist
122 ch_open() fails quickly. On MS-Windows "waittime" applies. 182 ch_open() fails quickly. On MS-Windows "waittime" applies.
124 184
125 If there is an error reading or writing a channel it will be closed. 185 If there is an error reading or writing a channel it will be closed.
126 *E896* *E630* *E631* 186 *E896* *E630* *E631*
127 187
128 ============================================================================== 188 ==============================================================================
129 3. Using a JSON or JS channel *channel-use* 189 4. Using a JSON or JS channel *channel-use*
130 190
131 If {mode} is "json" then a message can be sent synchronously like this: > 191 If {mode} is "json" then a message can be sent synchronously like this: >
132 let response = ch_sendexpr(handle, {expr}) 192 let response = ch_sendexpr(channel, {expr})
133 This awaits a response from the other side. 193 This awaits a response from the other side.
134 194
135 When {mode} is "js" this works the same, except that the messages use 195 When {mode} is "js" this works the same, except that the messages use
136 JavaScript encoding. See |jsencode()| for the difference. 196 JavaScript encoding. See |js_encode()| for the difference.
137 197
138 To send a message, without handling a response: > 198 To send a message, without handling a response: >
139 call ch_sendexpr(handle, {expr}, 0) 199 call ch_sendexpr(channel, {expr}, 0)
140 200
141 To send a message and letting the response handled by a specific function, 201 To send a message and letting the response handled by a specific function,
142 asynchronously: > 202 asynchronously: >
143 call ch_sendexpr(handle, {expr}, {callback}) 203 call ch_sendexpr(channel, {expr}, {callback})
204
205 Vim will match the response with the request using the message ID. Once the
206 response is received the callback will be invoked. Further responses with the
207 same ID will be ignored. If your server sends back multiple responses you
208 need to send them with ID zero, they will be passed to the channel callback.
144 209
145 The {expr} is converted to JSON and wrapped in an array. An example of the 210 The {expr} is converted to JSON and wrapped in an array. An example of the
146 message that the receiver will get when {expr} is the string "hello": 211 message that the receiver will get when {expr} is the string "hello":
147 [12,"hello"] ~ 212 [12,"hello"] ~
148 213
173 238
174 It is also possible to use ch_sendraw() on a JSON or JS channel. The caller 239 It is also possible to use ch_sendraw() on a JSON or JS channel. The caller
175 is then completely responsible for correct encoding and decoding. 240 is then completely responsible for correct encoding and decoding.
176 241
177 ============================================================================== 242 ==============================================================================
178 4. Vim commands *channel-commands* 243 5. Channel commands *channel-commands*
179
180 PARTLY IMPLEMENTED: only "ex" and "normal" work
181 244
182 With a "json" channel the process can send commands to Vim that will be 245 With a "json" channel the process can send commands to Vim that will be
183 handled by Vim internally, it does not require a handler for the channel. 246 handled by Vim internally, it does not require a handler for the channel.
184 247
185 Possible commands are: *E903* *E904* *E905* 248 Possible commands are: *E903* *E904* *E905*
249 The "expr" command is similar to "eval", but does not send back any response. 312 The "expr" command is similar to "eval", but does not send back any response.
250 Example: 313 Example:
251 ["expr","setline('$', ['one', 'two', 'three'])"] ~ 314 ["expr","setline('$', ['one', 'two', 'three'])"] ~
252 315
253 ============================================================================== 316 ==============================================================================
254 5. Using a raw channel *channel-raw* 317 6. Using a RAW or NL channel *channel-raw*
255 318
256 If {mode} is "raw" then a message can be send like this: > 319 If {mode} is "raw" then a message can be send like this: >
257 let response = ch_sendraw(handle, {string}) 320 let response = ch_sendraw(channel, {string})
258 The {string} is sent as-is. The response will be what can be read from the 321 The {string} is sent as-is. The response will be what can be read from the
259 channel right away. Since Vim doesn't know how to recognize the end of the 322 channel right away. Since Vim doesn't know how to recognize the end of the
260 message you need to take care of it yourself. 323 message you need to take care of it yourself. The timeout applies for reading
324 the first byte, after that it will not wait for anything more.
325
326 If {mode} is "nl" you can send a message in a similar way. You are expected
327 to put in the NL after each message. Thus you can also send several messages
328 ending in a NL at once. The response will be the text up to and including the
329 first NL. This can also be just the NL for an empty response.
330 If no NL was read before the channel timeout an empty string is returned.
261 331
262 To send a message, without expecting a response: > 332 To send a message, without expecting a response: >
263 call ch_sendraw(handle, {string}, 0) 333 call ch_sendraw(channel, {string}, 0)
264 The process can send back a response, the channel handler will be called with 334 The process can send back a response, the channel handler will be called with
265 it. 335 it.
266 336
267 To send a message and letting the response handled by a specific function, 337 To send a message and letting the response handled by a specific function,
268 asynchronously: > 338 asynchronously: >
269 call ch_sendraw(handle, {string}, {callback}) 339 call ch_sendraw(channel, {string}, {callback})
270 340
271 This {string} can also be JSON, use |jsonencode()| to create it and 341 This {string} can also be JSON, use |json_encode()| to create it and
272 |jsondecode()| to handle a received JSON message. 342 |json_decode()| to handle a received JSON message.
273 343
274 It is not possible to use |ch_sendexpr()| on a raw channel. 344 It is not possible to use |ch_sendexpr()| on a raw channel.
275 345
276 ============================================================================== 346 ==============================================================================
277 6. Job control *job-control* 347 7. More channel functions *channel-more*
278 348
279 NOT IMPLEMENTED YET 349 To obtain the status of a channel: ch_status(channel). The possible results
280 350 are:
281 To start another process: > 351 "fail" Failed to open the channel.
282 call startjob({command}) 352 "open" The channel can be used.
283 353 "closed" The channel was closed.
284 This does not wait for {command} to exit.
285 354
286 TODO: 355 TODO:
287 356 To objain the job associated with a channel: ch_getjob(channel)
288 let handle = startjob({command}, 's') # uses stdin/stdout 357
289 let handle = startjob({command}, '', {address}) # uses socket 358 TODO:
290 let handle = startjob({command}, 'd', {address}) # start if connect fails 359 To read one message from a channel: >
360 let output = ch_read(channel)
361 This uses the channel timeout. To read without a timeout, just get any
362 message that is available: >
363 let output = ch_read(channel, 0)
364 When no message was available then the result is v:none for a JSON or JS mode
365 channels, an empty string for a RAW or NL channel.
366
367 To read all output from a RAW or NL channel that is available: >
368 let output = ch_readall(channel)
369 To read the error output: >
370 let output = ch_readall(channel, "err")
371 TODO: use channel timeout, no timeout or specify timeout?
372
373 ==============================================================================
374 8. Starting a job with a channel *job-start* *job*
375
376 To start a job and open a channel for stdin/stdout/stderr: >
377 let job = job_start(command, {options})
378
379 You can get the channel with: >
380 let channel = job_getchannel(job)
381
382 The channel will use NL mode. If you want another mode it's best to specify
383 this in {options}. When changing the mode later some text may have already
384 been received and not parsed correctly.
385
386 If the command produces a line of output that you want to deal with, specify
387 a handler for stdout: >
388 let job = job_start(command, {"out-cb": "MyHandler"})
389 The function will be called with the channel and a message. You would define
390 it like this: >
391 func MyHandler(channel, msg)
392
393 Without the handler you need to read the output with ch_read().
394
395 The handler defined for "out-cb" will also receive stderr. If you want to
396 handle that separately, add an "err-cb" handler: >
397 let job = job_start(command, {"out-cb": "MyHandler",
398 \ "err-cb": "ErrHandler"})
399
400 You can send a message to the command with ch_sendraw(). If the channel is in
401 JSON or JS mode you can use ch_sendexpr().
402
403 There are several options you can use, see |job-options|.
404
405 TODO:
406 To run a job and read its output once it is done: >
407
408 let job = job_start({command}, {'exit-cb': 'MyHandler'})
409 func MyHandler(job, status)
410 let channel = job_getchannel()
411 let output = ch_readall(channel)
412 " parse output
413 endfunc
414
415 ==============================================================================
416 9. Starting a job without a channel *job-start-nochannel*
417
418 To start another process without creating a channel: >
419 let job = job_start(command, {"in-io": "null", "out-io": "null"})
420
421 This starts {command} in the background, Vim does not wait for it to finish.
422
423 TODO:
424 When Vim sees that neither stdin, stdout or stderr are connected, no channel
425 will be created. Often you will want to include redirection in the command to
426 avoid it getting stuck.
427
428 There are several options you can use, see |job-options|.
429
430 TODO: *job-may-start*
431 To start a job only when connecting to an address does not work use
432 job_maystart('command', {address}, {options}), For Example: >
433 let job = job_maystart(command, address, {"waittime": 1000})
434 let channel = job_gethandle(job)
435
436 This comes down to: >
437 let channel = ch_open(address, {"waittime": 0})
438 if ch_status(channel) == "fail"
439 let job = job_start(command)
440 let channel = ch_open(address, {"waittime": 1000})
441 call job_sethandle(channel)
442 endif
443 Note that the specified waittime applies to when the job has been started.
444 This gives the job some time to make the port available.
445
446 ==============================================================================
447 10. Job options *job-options*
448
449 The {options} argument in job_start() is a dictionary. All entries are
450 optional. The same options can be used with job_setoptions(job, {options}).
451
452 TODO: *job-out-cb*
453 "out-cb": handler Callback for when there is something to read on
454 stdout.
455 TODO: *job-err-cb*
456 "err-cb": handler Callback for when there is something to read on
457 stderr. Defaults to the same callback as "out-cb".
458 TODO: *job-close-cb*
459 "close-cb": handler Callback for when the channel is closed. Same as
460 "close-cb" on ch_open().
461 TODO: *job-exit-cb*
462 "exit-cb": handler Callback for when the job ends. The arguments are the
463 job and the exit status.
464 TODO: *job-killonexit*
465 "killonexit": 1 Stop the job when Vim exits.
466 "killonexit": 0 Do not stop the job when Vim exits.
467 The default is 1.
468 TODO: *job-term*
469 "term": "open" Start a terminal and connect the job
470 stdin/stdout/stderr to it.
471
472 TODO: *job-in-io*
473 "in-io": "null" disconnect stdin
474 "in-io": "pipe" stdin is connected to the channel (default)
475 "in-io": "file" stdin reads from a file
476 "in-file": "/path/file" the file to read from
477
478 TODO: *job-out-io*
479 "out-io": "null" disconnect stdout
480 "out-io": "pipe" stdout is connected to the channel (default)
481 "out-io": "file" stdout writes to a file
482 "out-file": "/path/file" the file to write to
483 "out-io": "buffer" stdout appends to a buffer
484 "out-buffer": "name" buffer to append to
485
486 TODO: *job-err-io*
487 "err-io": "out" same as stdout (default)
488 "err-io": "null" disconnect stderr
489 "err-io": "pipe" stderr is connected to the channel
490 "err-io": "file" stderr writes to a file
491 "err-file": "/path/file" the file to write to
492 "err-io": "buffer" stderr appends to a buffer
493 "err-buffer": "name" buffer to append to
494
495 TODO: more options
496
497
498 ==============================================================================
499 11. Controlling a job *job-control*
500
501 To get the status of a job: >
502 echo job_status(job)
503
504 To make a job stop running: >
505 job_stop(job)
506
507 This is the normal way to end a job. On Unix it sends a SIGTERM to the job.
508 It is possible to use other ways to stop the job, or even send arbitrary
509 signals. E.g. to force a job to stop, "kill it": >
510 job_stop(job, "kill")
511
512 For more options see |job_stop()|.
291 513
292 514
293 vim:tw=78:ts=8:ft=help:norl: 515 vim:tw=78:ts=8:ft=help:norl: