Mercurial > vim

comparison runtime/doc/channel.txt @ 8178:e77efd7a7dad v7.4.1382

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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)