Changeset 487:e68724ac688d for ftputil.txt

Timestamp:

2006-02-06 22:39:20 (5 years ago)

Author:

Stefan Schwarzer <sschwarzer@…>

Branch:

default

convert_revision:

svn:778c30c8-61e0-0310-89d4-fe2f97a467b2/trunk@506

Message:

Added an optional parameter `also_files` to `FTPHost.keep_alive`
and documented it in `ftputil.txt`.

Files:

• ftputil.txt (modified) (3 diffs)

ftputil.txt

@@ -654 +654 @@
   and use of remote file-like objects.
 
-- ``keep_alive()``
+.. _`FTPHost.keep_alive`:
+
+- ``keep_alive(also_files=True)``
 
   Do something without side effects to hold the connection to the FTP
   server. This should be used to prevent server timeouts after several
   minutes of inactivity.
+
+  Note that not only an ``FTPHost`` object but also *each* of the
+  file-objects made from it has its own connection to the FTP server,
+  so all of the connections must be kept alive. Use the default
+  setting, ``True``, for ``also_files`` to propagate the refresh to
+  all open file-like objects made from this ``FTPHost`` instance.
+
+  However, be careful with the default parameter in multi-threaded
+  applications.
 
 
@@ -711 +722 @@
   server. This should be used to prevent server timeouts after several
   minutes of inactivity.
+
+  Note that not only an ``FTPHost`` object but also *each* of the
+  file-objects made from it has its own connection to the FTP server,
+  so all of the connections must be kept alive. Use the
+  `FTPHost.keep_alive`_ to refresh all connections at once.
 
 
@@ -816 +832 @@
 - Timeouts of individual child sessions currently are not handled.
   This is only a problem if your ``FTPHost`` object or the generated
-  ``FTPFile`` objects are inactive for about ten minutes or longer. A
-  workaround is to keep the respective connections busy, e. g. call
-  ``getcwd`` on ``FTPHost`` objects or ``write("")`` on remote
-  file-like objects.
+  ``FTPFile`` objects are inactive for about ten minutes or longer.
+  As a workaround, you can use the ``keep_alive`` methods of
+  ``FTPHost`` objects and remote file-like objects.
 
 - Until now, I haven't paid attention to thread safety. In principle,