guile-commits
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Guile-commits] 01/01: Document char-ready? limitations.


From: Andy Wingo
Subject: [Guile-commits] 01/01: Document char-ready? limitations.
Date: Mon, 20 Jun 2016 19:23:37 +0000 (UTC)

wingo pushed a commit to branch master
in repository guile.

commit 5b6eaa91d23199f9266a3c338b8be8dcad5ecc38
Author: Andy Wingo <address@hidden>
Date:   Mon Jun 20 21:21:20 2016 +0200

    Document char-ready? limitations.
    
    * doc/ref/api-io.texi (Venerable Port Interfaces): Document limitations
      of char-ready?.  See http://debbugs.gnu.org/10627.
---
 doc/ref/api-io.texi |   16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 9b32c87..48ff177 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1410,6 +1410,22 @@ has been asserted by @code{char-ready?} cannot be rubbed 
out.
 If @code{char-ready?} were to return @code{#f} at end of file,
 a port at end of file would be indistinguishable from an
 interactive port that has no ready characters.
+
+Note that @code{char-ready?} only works reliably for terminals and
+sockets with one-byte encodings.  Under the hood it will return
address@hidden if the port has any input buffered, or if the file descriptor
+that backs the port polls as readable, indicating that Guile can fetch
+more bytes from the kernel.  However being able to fetch one byte
+doesn't mean that a full character is available; @xref{Encoding}.  Also,
+on many systems it's possible for a file descriptor to poll as readable,
+but then block when it comes time to read bytes.  Note also that on
+Linux kernels, all file ports backed by files always poll as readable.
+For non-file ports, this procedure always returns @code{#t}, except for
+soft ports, which have a @code{char-ready?} handler.  @xref{Soft Ports}.
+
+In short, this is a legacy procedure whose semantics are hard to
+provide.  However it is a useful check to see if any input is buffered.
address@hidden I/O}.
 @end deffn
 
 @rnindex read-char



reply via email to

[Prev in Thread] Current Thread [Next in Thread]