From 4b785f69c0616dba5d3f38e8ce4b5398cec89407 Mon Sep 17 00:00:00 2001 From: Bram Moolenaar Date: Tue, 29 Nov 2016 21:54:44 +0100 Subject: patch 8.0.0105 Problem: When using ch_read() with zero timeout, can't tell the difference between reading an empty line and nothing available. Solution: Add ch_canread(). --- runtime/doc/channel.txt | 11 ++++++++++- runtime/doc/eval.txt | 31 ++++++++++++++++++++++--------- 2 files changed, 32 insertions(+), 10 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 73105986f..2c3f83730 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -418,7 +418,11 @@ This uses the channel timeout. To read without a timeout, just get any message that is available: > let output = ch_read(channel, {'timeout': 0}) When no message was available then the result is v:none for a JSON or JS mode -channels, an empty string for a RAW or NL channel. +channels, an empty string for a RAW or NL channel. You can use |ch_canread()| +to check if there is something to read. + +Note that when there is no callback message are dropped. To avoid that add a +close callback to the channel. To read all output from a RAW channel that is available: > let output = ch_readraw(channel) @@ -470,6 +474,11 @@ This depends on the system (on Unix this happens because closing the write end of a pipe causes the read end to get EOF). To avoid this make the job sleep for a short while before it exits. +Note that if the job exits before you read the output, the output may be lost. +This depends on the system (on Unix this happens because closing the write end +of a pipe causes the read end to get EOF). To avoid this make the job sleep +for a short while before it exits. + 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", diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 1a11a4141..75c2ea113 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2009,6 +2009,7 @@ byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr} call({func}, {arglist} [, {dict}]) any call {func} with arguments {arglist} ceil({expr}) Float round {expr} up +ch_canread({handle}) Number check if there is something to read ch_close({handle}) none close {handle} ch_close_in({handle}) none close in part of {handle} ch_evalexpr({handle}, {expr} [, {options}]) @@ -2980,16 +2981,28 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) don't fit, a vertical layout is used anyway. For some systems the horizontal layout is always used. +ch_canread({handle}) *ch_canread()* + Return non-zero when there is something to read from {handle}. + {handle} can be a Channel or a Job that has a Channel. + + This is useful to read from a channel at a convenient time, + e.g. from a timer. + + Note that messages are dropped when the channel does not have + a callback. Add a close callback to avoid that. + + {only available when compiled with the |+channel| feature} + ch_close({handle}) *ch_close()* Close {handle}. See |channel-close|. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. A close callback is not invoked. {only available when compiled with the |+channel| feature} ch_close_in({handle}) *ch_close_in()* Close the "in" part of {handle}. See |channel-close-in|. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. A close callback is not invoked. {only available when compiled with the |+channel| feature} @@ -2998,7 +3011,7 @@ ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()* Send {expr} over {handle}. The {expr} is encoded according to the type of channel. The function cannot be used with a raw channel. See |channel-use|. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. *E917* {options} must be a Dictionary. It must not have a "callback" entry. It can have a "timeout" entry to specify the timeout @@ -3012,7 +3025,7 @@ ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()* ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()* Send {string} over {handle}. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. Works like |ch_evalexpr()|, but does not encode the request or decode the response. The caller is responsible for the @@ -3025,7 +3038,7 @@ ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()* ch_getbufnr({handle}, {what}) *ch_getbufnr()* Get the buffer number that {handle} is using for {what}. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. {what} can be "err" for stderr, "out" for stdout or empty for socket output. Returns -1 when there is no buffer. @@ -3099,7 +3112,7 @@ ch_open({address} [, {options}]) *ch_open()* ch_read({handle} [, {options}]) *ch_read()* Read from {handle} and return the received message. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. See |channel-more|. {only available when compiled with the |+channel| feature} @@ -3113,7 +3126,7 @@ ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()* according to the type of channel. The function cannot be used with a raw channel. See |channel-use|. *E912* - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. {only available when compiled with the |+channel| feature} @@ -3134,7 +3147,7 @@ ch_setoptions({handle}, {options}) *ch_setoptions()* "timeout" default read timeout in msec "mode" mode for the whole channel See |ch_open()| for more explanation. - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. Note that changing the mode may cause queued messages to be lost. @@ -3148,7 +3161,7 @@ ch_status({handle} [, {options}]) *ch_status()* "open" channel can be used "buffered" channel can be read, not written to "closed" channel can not be used - {handle} can be Channel or a Job that has a Channel. + {handle} can be a Channel or a Job that has a Channel. "buffered" is used when the channel was closed but there is still data that can be obtained with |ch_read()|. -- cgit v1.2.1