Add more documentation about glib file watches

a-sync/gnome-glib.scm

@@ -153,6 +153,10 @@
 ;; glib ID which can be passed subsequently to the g-source-remove
 ;; procedure.  It should be possible to call this procedure in any
 ;; thread.
+;;
+;; See the documentation on the a-sync-glib-read-watch procedure for
+;; some of the difficulties with using g-io-channel watches with
+;; guile-gnome.
 (define* (glib-add-watch ioc cond func #:optional context)
   (let ((s (g-io-create-watch ioc cond))
         (closure (make <gclosure>
@@ -179,6 +183,22 @@
 ;; higher-level asynchronous file operations can be constructed, such
 ;; as the await-glib-getline procedure.
 ;;
+;; File watches in guile-gnome are implemented using a GIOChannel
+;; object, and unfortunately GIOChannel support in guile-gnome is
+;; decaying.  The only procedure that guile-gnome provides to read
+;; from a GIOChannel object is g-io-channel-read-line, which does not
+;; work.  One is therefore usually left with having to read from a
+;; guile port (whose underlying file descriptor is 'fd') using guile's
+;; port input procedures, but this has its own difficulties because
+;; either the port has to be unbuffered (say by using the R6RS
+;; open-file-input-port procedure with a buffer-mode of none), or
+;; 'proc' must deal with everything in the port's buffer by looping on
+;; char-ready? before returning.  This is because if the port is
+;; buffered, once the port is read from there may be further
+;; characters in the buffer to be dealt with even though the
+;; GIOChannel watch does not trigger because there is nothing new to
+;; make the file descriptor ready for reading.
+;;
 ;; Because this procedure takes a 'resume' argument derived from the
 ;; a-sync procedure, it must (like the a-sync procedure) in practice
 ;; be called in the same thread as that in which the default glib main
@@ -209,10 +229,12 @@
 ;; text, the end-of-file object is returned rather than an empty
 ;; string).
 ;;
-;; This procedure only works correctly if the port passed to the
-;; 'port' argument has buffering switched off, say by using the R6RS
-;; open-file-input-port procedure with a buffer-mode of none.  This
-;; makes the procedure less useful than would otherwise be the case.
+;; For the reasons explained in the documentation on
+;; a-sync-glib-read-watch, this procedure only works correctly if the
+;; port passed to the 'port' argument has buffering switched off, say
+;; by using the R6RS open-file-input-port procedure with a buffer-mode
+;; of none.  This makes the procedure less useful than would otherwise
+;; be the case.
 ;;
 ;; This procedure must (like the a-sync procedure) be called in the
 ;; same thread as that in which the default glib main loop runs.
@@ -283,6 +305,13 @@
 ;; This procedure is mainly intended as something from which
 ;; higher-level asynchronous file operations can be constructed.
 ;;
+;; The documentation on the a-sync-glib-read-watch procedure comments
+;; about about the difficulties of using GIOChannel file watches with
+;; buffered ports.  The difficulties are not quite so intense with
+;; write watches, but users are likely to get best results by using
+;; unbuffered output ports (say by using the R6RS
+;; open-file-output-port procedure with a buffer-mode of none).
+;;
 ;; Because this procedure takes a 'resume' argument derived from the
 ;; a-sync procedure, it must (like the a-sync procedure) in practice
 ;; be called in the same thread as that in which the default glib main

docs/gnome-glib.texi

@@ -141,6 +141,10 @@ main context provided, or if none is provided, to the default glib
 main context (the main program loop).  It returns a glib ID which can
 be passed subsequently to the g-source-remove procedure.  It should be
 possible to call this procedure in any thread.
+
+See the documentation on the a-sync-glib-read-watch procedure for
+some of the difficulties with using g-io-channel watches with
+guile-gnome.
 @end deffn
 
 @deffn {Scheme Procedure} a-sync-glib-read-watch resume fd proc
@@ -161,6 +165,21 @@ while the read watch is active.  This procedure is mainly intended as
 something from which higher-level asynchronous file operations can be
 constructed, such as the await-glib-getline procedure.
 
+File watches in guile-gnome are implemented using a GIOChannel object,
+and unfortunately GIOChannel support in guile-gnome is decaying.  The
+only procedure that guile-gnome provides to read from a GIOChannel
+object is g-io-channel-read-line, which does not work.  One is
+therefore usually left with having to read from a guile port (whose
+underlying file descriptor is 'fd') using guile's port input
+procedures, but this has its own difficulties because either the port
+has to be unbuffered (say by using the R6RS open-file-input-port
+procedure with a buffer-mode of none), or 'proc' must deal with
+everything in the port's buffer by looping on char-ready? before
+returning.  This is because if the port is buffered, once the port is
+read from there may be further characters in the buffer to be dealt
+with even though the GIOChannel watch does not trigger because there
+is nothing new to make the file descriptor ready for reading.
+
 Because this procedure takes a 'resume' argument derived from the
 a-sync procedure, it must (like the a-sync procedure) in practice be
 called in the same thread as that in which the default glib main loop
@@ -227,10 +246,12 @@ line of text will be returned (and from version 0.3, if an end-of-file
 object is encountered without any text, the end-of-file object is
 returned rather than an empty string).
 
-This procedure only works correctly if the port passed to the 'port'
-argument has buffering switched off, say by using the R6RS
-open-file-input-port procedure with a buffer-mode of none.  This makes
-the procedure less useful than would otherwise be the case.
+For the reasons explained in the documentation on
+a-sync-glib-read-watch, this procedure only works correctly if the
+port passed to the 'port' argument has buffering switched off, say by
+using the R6RS open-file-input-port procedure with a buffer-mode of
+none.  This makes the procedure less useful than would otherwise be
+the case.
 
 This procedure must (like the a-sync procedure) be called in the same
 thread as that in which the default glib main loop runs.
@@ -272,6 +293,13 @@ while the read watch is active.  This procedure is mainly intended as
 something from which higher-level asynchronous file operations can be
 constructed.
 
+The documentation on the a-sync-glib-read-watch procedure comments
+about about the difficulties of using GIOChannel file watches with
+buffered ports.  The difficulties are not quite so intense with write
+watches, but users are likely to get best results by using unbuffered
+output ports (say by using the R6RS open-file-output-port procedure
+with a buffer-mode of none).
+
 Because this procedure takes a 'resume' argument derived from the
 a-sync procedure, it must (like the a-sync procedure) in practice be
 called in the same thread as that in which the default glib main loop

docs/guile-a-sync.info

@@ -1022,6 +1022,10 @@ module, so as not to create a hard dependency on guile-gnome.
      procedure.  It should be possible to call this procedure in any
      thread.
 
+     See the documentation on the a-sync-glib-read-watch procedure for
+     some of the difficulties with using g-io-channel watches with
+     guile-gnome.
+
  -- Scheme Procedure: a-sync-glib-read-watch resume fd proc
      This is a convenience procedure for use with a glib main loop,
      which will run 'proc' in the default glib main loop whenever the
@@ -1041,6 +1045,22 @@ module, so as not to create a hard dependency on guile-gnome.
      higher-level asynchronous file operations can be constructed, such
      as the await-glib-getline procedure.
 
+     File watches in guile-gnome are implemented using a GIOChannel
+     object, and unfortunately GIOChannel support in guile-gnome is
+     decaying.  The only procedure that guile-gnome provides to read
+     from a GIOChannel object is g-io-channel-read-line, which does not
+     work.  One is therefore usually left with having to read from a
+     guile port (whose underlying file descriptor is 'fd') using guile's
+     port input procedures, but this has its own difficulties because
+     either the port has to be unbuffered (say by using the R6RS
+     open-file-input-port procedure with a buffer-mode of none), or
+     'proc' must deal with everything in the port's buffer by looping on
+     char-ready?  before returning.  This is because if the port is
+     buffered, once the port is read from there may be further
+     characters in the buffer to be dealt with even though the
+     GIOChannel watch does not trigger because there is nothing new to
+     make the file descriptor ready for reading.
+
      Because this procedure takes a 'resume' argument derived from the
      a-sync procedure, it must (like the a-sync procedure) in practice
      be called in the same thread as that in which the default glib main
@@ -1105,10 +1125,12 @@ module, so as not to create a hard dependency on guile-gnome.
      text, the end-of-file object is returned rather than an empty
      string).
 
-     This procedure only works correctly if the port passed to the
-     'port' argument has buffering switched off, say by using the R6RS
-     open-file-input-port procedure with a buffer-mode of none.  This
-     makes the procedure less useful than would otherwise be the case.
+     For the reasons explained in the documentation on
+     a-sync-glib-read-watch, this procedure only works correctly if the
+     port passed to the 'port' argument has buffering switched off, say
+     by using the R6RS open-file-input-port procedure with a buffer-mode
+     of none.  This makes the procedure less useful than would otherwise
+     be the case.
 
      This procedure must (like the a-sync procedure) be called in the
      same thread as that in which the default glib main loop runs.
@@ -1148,6 +1170,13 @@ module, so as not to create a hard dependency on guile-gnome.
      This procedure is mainly intended as something from which
      higher-level asynchronous file operations can be constructed.
 
+     The documentation on the a-sync-glib-read-watch procedure comments
+     about about the difficulties of using GIOChannel file watches with
+     buffered ports.  The difficulties are not quite so intense with
+     write watches, but users are likely to get best results by using
+     unbuffered output ports (say by using the R6RS
+     open-file-output-port procedure with a buffer-mode of none).
+
      Because this procedure takes a 'resume' argument derived from the
      a-sync procedure, it must (like the a-sync procedure) in practice
      be called in the same thread as that in which the default glib main
@@ -1283,6 +1312,6 @@ Node: coroutines1099
 Node: event loop14941
 Node: monotonic time44818
 Node: gnome glib46252
-Node: compose60352
+Node: compose62005
 
 End Tag Table