Mercurial > vim
comparison runtime/doc/channel.txt @ 8178:e77efd7a7dad v7.4.1382
commit https://github.com/vim/vim/commit/02e83b438ea7071fdb176dabbaefea319ab2d686
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Feb 21 20:10:26 2016 +0100
patch 7.4.1382
Problem: Can't get the job of a channel.
Solution: Add ch_getjob().
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Sun, 21 Feb 2016 20:15:04 +0100 |
parents | 9ca3885edfed |
children | f16bfe02cef1 |
comparison
equal
deleted
inserted
replaced
8177:0e3185eea369 | 8178:e77efd7a7dad |
---|---|
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 20 | 1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 21 |
2 | 2 |
3 | 3 |
4 VIM REFERENCE MANUAL by Bram Moolenaar | 4 VIM REFERENCE MANUAL by Bram Moolenaar |
5 | 5 |
6 | 6 |
91 | 91 |
92 To handle asynchronous communication a callback needs to be used: > | 92 To handle asynchronous communication a callback needs to be used: > |
93 func MyHandler(channel, msg) | 93 func MyHandler(channel, msg) |
94 echo "from the handler: " . a:msg | 94 echo "from the handler: " . a:msg |
95 endfunc | 95 endfunc |
96 call ch_sendexpr(channel, 'hello!', "MyHandler") | 96 call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"}) |
97 Vim will not wait for a response. Now the server can send the response later | 97 Vim will not wait for a response. Now the server can send the response later |
98 and MyHandler will be invoked. | 98 and MyHandler will be invoked. |
99 | 99 |
100 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 |
101 when opening the channel: > | 101 when opening the channel: > |
102 call ch_close(channel) | 102 call ch_close(channel) |
103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) | 103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"}) |
104 call ch_sendexpr(channel, 'hello!', 0) | 104 call ch_sendexpr(channel, 'hello!', {'callback': 0}) |
105 | 105 |
106 ============================================================================== | 106 ============================================================================== |
107 3. Opening a channel *channel-open* | 107 3. Opening a channel *channel-open* |
108 | 108 |
109 To open a channel: > | 109 To open a channel: > |
110 let channel = ch_open({address} [, {options}]) | 110 let channel = ch_open({address} [, {options}]) |
111 if ch_status(channel) == "open" | |
112 " use the channel | |
111 | 113 |
112 Use |ch_status()| to see if the channel could be opened. | 114 Use |ch_status()| to see if the channel could be opened. |
113 | 115 |
114 {address} has the form "hostname:port". E.g., "localhost:8765". | 116 {address} has the form "hostname:port". E.g., "localhost:8765". |
115 | 117 |
129 mode later. | 131 mode later. |
130 | 132 |
131 *channel-callback* | 133 *channel-callback* |
132 "callback" A function that is called when a message is received that is | 134 "callback" A function that is called when a message is received that is |
133 not handled otherwise. It gets two arguments: the channel | 135 not handled otherwise. It gets two arguments: the channel |
134 handle and the received message. Example: > | 136 and the received message. Example: > |
135 func Handle(channel, msg) | 137 func Handle(channel, msg) |
136 echo 'Received: ' . a:msg | 138 echo 'Received: ' . a:msg |
137 endfunc | 139 endfunc |
138 let channel = ch_open("localhost:8765", {"callback": "Handle"}) | 140 let channel = ch_open("localhost:8765", {"callback": "Handle"}) |
139 < | 141 < |
142 When "mode" is "json" or "js" the "msg" argument is the body | |
143 of the received message, converted to Vim types. | |
144 When "mode" is "nl" the "msg" argument is one message, | |
145 excluding the NL. | |
146 When "mode" is "raw" the "msg" argument is the whole message | |
147 as a string. | |
148 *out-cb* | |
140 "out-cb" A function like "callback" but used for stdout. Only for when | 149 "out-cb" A function like "callback" but used for stdout. Only for when |
141 the channel uses pipes. When "out-cb" wasn't set the channel | 150 the channel uses pipes. When "out-cb" wasn't set the channel |
142 callback is used. | 151 callback is used. |
143 | 152 *err-cb* |
144 "err-cb" A function like "callback" but used for stderr. Only for when | 153 "err-cb" A function like "callback" but used for stderr. Only for when |
145 the channel uses pipes. When "err-cb" wasn't set the channel | 154 the channel uses pipes. When "err-cb" wasn't set the channel |
146 callback is used. | 155 callback is used. |
147 | 156 |
148 TODO: | 157 TODO: *close-cb* |
149 "close-cb" A function that is called when the channel gets closed, other | 158 "close-cb" A function that is called when the channel gets closed, other |
150 than by calling ch_close(). It should be defined like this: > | 159 than by calling ch_close(). It should be defined like this: > |
151 func MyCloseHandler(channel) | 160 func MyCloseHandler(channel) |
152 | 161 < *waittime* |
153 "waittime" The time to wait for the connection to be made in | 162 "waittime" The time to wait for the connection to be made in |
154 milliseconds. The default is zero, don't wait, which is | 163 milliseconds. The default is zero, don't wait, which is |
155 useful if the server is supposed to be running already. A | 164 useful if the server is supposed to be running already. A |
156 negative number waits forever. | 165 negative number waits forever. |
157 | 166 |
158 "timeout" The time to wait for a request when blocking, E.g. when using | 167 "timeout" The time to wait for a request when blocking, E.g. when using |
159 ch_sendexpr(). In milliseconds. The default is 2000 (2 | 168 ch_sendexpr(). In milliseconds. The default is 2000 (2 |
160 seconds). | 169 seconds). |
161 | 170 *out-timeout* *err-timeout* |
162 "out-timeout" Timeout for stdout. Only when using pipes. | 171 "out-timeout" Timeout for stdout. Only when using pipes. |
163 "err-timeout" Timeout for stderr. Only when using pipes. | 172 "err-timeout" Timeout for stderr. Only when using pipes. |
164 Note: when setting "timeout" the part specific mode is | 173 Note: when setting "timeout" the part specific mode is |
165 overwritten. Therefore set "timeout" first and the part | 174 overwritten. Therefore set "timeout" first and the part |
166 specific mode later. | 175 specific mode later. |
167 | 176 |
168 When "mode" is "json" or "js" the "msg" argument is the body of the received | |
169 message, converted to Vim types. | |
170 When "mode" is "raw" the "msg" argument is the whole message as a string. | |
171 | |
172 When "mode" is "json" or "js" the "callback" is optional. When omitted it is | 177 When "mode" is "json" or "js" the "callback" is optional. When omitted it is |
173 only possible to receive a message after sending one. | 178 only possible to receive a message after sending one. |
174 | 179 |
175 To change the channel options after opening it use ch_setoptions(). The | 180 To change the channel options after opening it use |ch_setoptions()|. The |
176 arguments are similar to what is passed to ch_open(), but "waittime" cannot be | 181 arguments are similar to what is passed to |ch_open()|, but "waittime" cannot |
177 given, since that only applies to opening the channel. | 182 be given, since that only applies to opening the channel. |
178 | 183 |
179 The handler can be added or changed: > | 184 For example, the handler can be added or changed: > |
180 call ch_setoptions(channel, {'callback': callback}) | 185 call ch_setoptions(channel, {'callback': callback}) |
181 When "callback" is empty (zero or an empty string) the handler is removed. | 186 When "callback" is empty (zero or an empty string) the handler is removed. |
182 | 187 |
183 The timeout can be changed: > | 188 The timeout can be changed: > |
184 call ch_setoptions(channel, {'timeout': msec}) | 189 call ch_setoptions(channel, {'timeout': msec}) |
185 < | 190 < |
186 *E906* | 191 *channel-close* *E906* |
187 Once done with the channel, disconnect it like this: > | 192 Once done with the channel, disconnect it like this: > |
188 call ch_close(channel) | 193 call ch_close(channel) |
189 When a socket is used this will close the socket for both directions. When | 194 When a socket is used this will close the socket for both directions. When |
190 pipes are used (stdin/stdout/stderr) they are all closed. This might not be | 195 pipes are used (stdin/stdout/stderr) they are all closed. This might not be |
191 what you want! Stopping the job with job_stop() might be better. | 196 what you want! Stopping the job with job_stop() might be better. |
192 | 197 |
193 TODO: | |
194 Currently up to 10 channels can be in use at the same time. *E897* | |
195 | |
196 When the channel can't be opened you will get an error message. There is a | 198 When the channel can't be opened you will get an error message. There is a |
197 difference between MS-Windows and Unix: On Unix when the port doesn't exist | 199 difference between MS-Windows and Unix: On Unix when the port doesn't exist |
198 ch_open() fails quickly. On MS-Windows "waittime" applies. | 200 ch_open() fails quickly. On MS-Windows "waittime" applies. |
199 *E898* *E899* *E900* *E901* *E902* | 201 *E898* *E899* *E900* *E901* *E902* |
200 | 202 |
209 This awaits a response from the other side. | 211 This awaits a response from the other side. |
210 | 212 |
211 When mode is JS this works the same, except that the messages use | 213 When mode is JS this works the same, except that the messages use |
212 JavaScript encoding. See |js_encode()| for the difference. | 214 JavaScript encoding. See |js_encode()| for the difference. |
213 | 215 |
214 To send a message, without handling a response: > | 216 To send a message, without handling a response or letting the channel callback |
215 call ch_sendexpr(channel, {expr}, 0) | 217 handle the response: > |
218 call ch_sendexpr(channel, {expr}, {'callback': 0}) | |
216 | 219 |
217 To send a message and letting the response handled by a specific function, | 220 To send a message and letting the response handled by a specific function, |
218 asynchronously: > | 221 asynchronously: > |
219 call ch_sendexpr(channel, {expr}, {callback}) | 222 call ch_sendexpr(channel, {expr}, {'callback': Handler}) |
220 | 223 |
221 Vim will match the response with the request using the message ID. Once the | 224 Vim will match the response with the request using the message ID. Once the |
222 response is received the callback will be invoked. Further responses with the | 225 response is received the callback will be invoked. Further responses with the |
223 same ID will be ignored. If your server sends back multiple responses you | 226 same ID will be ignored. If your server sends back multiple responses you |
224 need to send them with ID zero, they will be passed to the channel callback. | 227 need to send them with ID zero, they will be passed to the channel callback. |
422 let job = job_start(command, {"out-cb": "MyHandler"}) | 425 let job = job_start(command, {"out-cb": "MyHandler"}) |
423 The function will be called with the channel and a message. You would define | 426 The function will be called with the channel and a message. You would define |
424 it like this: > | 427 it like this: > |
425 func MyHandler(channel, msg) | 428 func MyHandler(channel, msg) |
426 | 429 |
427 Without the handler you need to read the output with ch_read(). | 430 Without the handler you need to read the output with |ch_read()| or |
428 | 431 |ch_readraw()|. |
429 The handler defined for "out-cb" will also receive stderr. If you want to | 432 |
433 The handler defined for "out-cb" will not receive stderr. If you want to | |
430 handle that separately, add an "err-cb" handler: > | 434 handle that separately, add an "err-cb" handler: > |
431 let job = job_start(command, {"out-cb": "MyHandler", | 435 let job = job_start(command, {"out-cb": "MyHandler", |
432 \ "err-cb": "ErrHandler"}) | 436 \ "err-cb": "ErrHandler"}) |
437 | |
438 If you want to handle both stderr and stdout with one handler use the | |
439 "callback" option: > | |
440 let job = job_start(command, {"callback": "MyHandler"}) | |
433 | 441 |
434 You can send a message to the command with ch_sendraw(). If the channel is in | 442 You can send a message to the command with ch_sendraw(). If the channel is in |
435 JSON or JS mode you can use ch_sendexpr(). | 443 JSON or JS mode you can use ch_sendexpr(). |
436 | 444 |
437 There are several options you can use, see |job-options|. | 445 There are several options you can use, see |job-options|. |
479 | 487 |
480 ============================================================================== | 488 ============================================================================== |
481 10. Job options *job-options* | 489 10. Job options *job-options* |
482 | 490 |
483 The {options} argument in job_start() is a dictionary. All entries are | 491 The {options} argument in job_start() is a dictionary. All entries are |
484 optional. The same options can be used with job_setoptions(job, {options}). | 492 optional. Some options can be used after the job has started, using |
493 job_setoptions(job, {options}). Many options can be used with the channel | |
494 related to the job, using ch_setoptions(channel, {options}). | |
495 See |job_setoptions()| and |ch_setoptions()|. | |
485 | 496 |
486 *job-callback* | 497 *job-callback* |
487 "callback": handler Callback for something to read on any part of the | 498 "callback": handler Callback for something to read on any part of the |
488 channel. | 499 channel. |
489 *job-out-cb* | 500 *job-out-cb* |
493 "err-cb": handler Callback for when there is something to read on | 504 "err-cb": handler Callback for when there is something to read on |
494 stderr. | 505 stderr. |
495 TODO: *job-close-cb* | 506 TODO: *job-close-cb* |
496 "close-cb": handler Callback for when the channel is closed. Same as | 507 "close-cb": handler Callback for when the channel is closed. Same as |
497 "close-cb" on ch_open(). | 508 "close-cb" on ch_open(). |
498 TODO: *job-exit-cb* | 509 *job-exit-cb* |
499 "exit-cb": handler Callback for when the job ends. The arguments are the | 510 "exit-cb": handler Callback for when the job ends. The arguments are the |
500 job and the exit status. | 511 job and the exit status. |
501 TODO: *job-killonexit* | 512 Vim checks about every 10 seconds for jobs that ended. |
502 "killonexit": 1 Stop the job when Vim exits. | 513 The callback can also be triggered by calling |
503 "killonexit": 0 Do not stop the job when Vim exits. | 514 |job_status()|. |
504 The default is 1. | 515 *job-stoponexit* |
516 "stoponexit": {signal} Send {signal} to the job when Vim exits. See | |
517 |job_stop()| for possible values. | |
518 "stoponexit": "" Do not stop the job when Vim exits. | |
519 The default is "term". | |
520 | |
505 TODO: *job-term* | 521 TODO: *job-term* |
506 "term": "open" Start a terminal and connect the job | 522 "term": "open" Start a terminal and connect the job |
507 stdin/stdout/stderr to it. | 523 stdin/stdout/stderr to it. |
508 | 524 |
509 TODO: *job-in-io* | 525 TODO: *job-in-io* |
527 "err-io": "file" stderr writes to a file | 543 "err-io": "file" stderr writes to a file |
528 "err-file": "/path/file" the file to write to | 544 "err-file": "/path/file" the file to write to |
529 "err-io": "buffer" stderr appends to a buffer | 545 "err-io": "buffer" stderr appends to a buffer |
530 "err-buffer": "name" buffer to append to | 546 "err-buffer": "name" buffer to append to |
531 | 547 |
532 TODO: more options | |
533 | |
534 | |
535 ============================================================================== | 548 ============================================================================== |
536 11. Controlling a job *job-control* | 549 11. Controlling a job *job-control* |
537 | 550 |
538 To get the status of a job: > | 551 To get the status of a job: > |
539 echo job_status(job) | 552 echo job_status(job) |