DOC: Modifications to documentation following PR 5369 review.

TST: Modifications to unit test following PR 5369 review.

Author: benalexau

doc/source/io.rst

@@ -2745,12 +2745,9 @@ Notes & Caveats
      need to serialize these operations in a single thread in a single
      process. You will corrupt your data otherwise. See the issue
      (:`2397`) for more information.
-   - If serializing all write operations via a single thread in a single
-     process is not an option, another alternative is to use an external
-     distributed lock manager to ensure there is only a single writer at a
-     time and all readers close the file during writes and re-open it after any
-     writes. In this case you should use ``store.flush(fsync=True)`` prior to
-     releasing any write locks. See the issue (:`5364`) for more information.
+   - If you use locks to manage write access between multiple processes, you
+     may want to use :py:func:`~os.fsync` before releasing write locks. For
+     convenience you can use ``store.flush(fsync=True)`` to do this for you.
    - ``PyTables`` only supports fixed-width string columns in
      ``tables``. The sizes of a string based indexing column
      (e.g. *columns* or *minor_axis*) are determined as the maximum size

pandas/io/pytables.py

@@ -530,21 +530,17 @@ def flush(self, fsync=False):
         """
         Force all buffered modifications to be written to disk.
 
-        By default this method requests PyTables to flush, and PyTables in turn
-        requests the HDF5 library to flush any changes to the operating system.
-        There is no guarantee the operating system will actually commit writes
-        to disk.
-
-        To request the operating system to write the file to disk, pass
-        ``fsync=True``. The method will then block until the operating system
-        reports completion, although be aware there might be other caching
-        layers (eg disk controllers, disks themselves etc) which further delay
-        durability.
-
         Parameters
         ----------
-        fsync : boolean, invoke fsync for the file handle, default False
+        fsync : bool (default False)
+          call ``os.fsync()`` on the file handle to force writing to disk.
 
+        Notes
+        -----
+        Without ``fsync=True``, flushing may not guarantee that the OS writes
+        to disk. With fsync, the operation will block until the OS claims the
+        file has been written; however, other caching layers may still
+        interfere.
         """
         if self._handle is not None:
             self._handle.flush()

pandas/io/tests/test_pytables.py

@@ -465,11 +465,6 @@ def test_flush(self):
         with ensure_clean(self.path) as store:
             store['a'] = tm.makeTimeSeries()
             store.flush()
-
-    def test_flush_fsync(self):
-
-        with ensure_clean(self.path) as store:
-            store['a'] = tm.makeTimeSeries()
             store.flush(fsync=True)
 
     def test_get(self):