summaryrefslogtreecommitdiffstats
path: root/doc/cephfs/lazyio.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/cephfs/lazyio.rst76
1 files changed, 76 insertions, 0 deletions
diff --git a/doc/cephfs/lazyio.rst b/doc/cephfs/lazyio.rst
new file mode 100644
index 000000000..b30058774
--- /dev/null
+++ b/doc/cephfs/lazyio.rst
@@ -0,0 +1,76 @@
+======
+LazyIO
+======
+
+LazyIO relaxes POSIX semantics. Buffered reads/writes are allowed even when a
+file is opened by multiple applications on multiple clients. Applications are
+responsible for managing cache coherency themselves.
+
+Libcephfs supports LazyIO since nautilus release.
+
+Enable LazyIO
+=============
+
+LazyIO can be enabled by following ways.
+
+- ``client_force_lazyio`` option enables LAZY_IO globally for libcephfs and
+ ceph-fuse mount.
+
+- ``ceph_lazyio(...)`` and ``ceph_ll_lazyio(...)`` enable LAZY_IO for file handle
+ in libcephfs.
+
+Using LazyIO
+============
+
+LazyIO includes two methods ``lazyio_propagate()`` and ``lazyio_synchronize()``.
+With LazyIO enabled, writes may not be visible to other clients until
+``lazyio_propagate()`` is called. Reads may come from local cache (irrespective of
+changes to the file by other clients) until ``lazyio_synchronize()`` is called.
+
+- ``lazyio_propagate(int fd, loff_t offset, size_t count)`` - Ensures that any
+ buffered writes of the client, in the specific region (offset to offset+count),
+ has been propagated to the shared file. If offset and count are both 0, the
+ operation is performed on the entire file. Currently only this is supported.
+
+- ``lazyio_synchronize(int fd, loff_t offset, size_t count)`` - Ensures that the
+ client is, in a subsequent read call, able to read the updated file with all
+ the propagated writes of the other clients. In CephFS this is facilitated by
+ invalidating the file caches pertaining to the inode and hence forces the
+ client to refetch/recache the data from the updated file. Also if the write cache
+ of the calling client is dirty (not propagated), lazyio_synchronize() flushes it as well.
+
+An example usage (utilizing libcephfs) is given below. This is a sample I/O loop for a
+particular client/file descriptor in a parallel application:
+
+::
+
+ /* Client a (ca) opens the shared file file.txt */
+ int fda = ceph_open(ca, "shared_file.txt", O_CREAT|O_RDWR, 0644);
+
+ /* Enable LazyIO for fda */
+ ceph_lazyio(ca, fda, 1));
+
+ for(i = 0; i < num_iters; i++) {
+ char out_buf[] = "fooooooooo";
+
+ ceph_write(ca, fda, out_buf, sizeof(out_buf), i);
+ /* Propagate the writes associated with fda to the backing storage*/
+ ceph_propagate(ca, fda, 0, 0);
+
+ /* The barrier makes sure changes associated with all file descriptors
+ are propagated so that there is certainty that the backing file
+ is up to date */
+ application_specific_barrier();
+
+ char in_buf[40];
+ /* Calling ceph_lazyio_synchronize here will ascertain that ca will
+ read the updated file with the propagated changes and not read
+ stale cached data */
+ ceph_lazyio_synchronize(ca, fda, 0, 0);
+ ceph_read(ca, fda, in_buf, sizeof(in_buf), 0);
+
+ /* A barrier is required here before returning to the next write
+ phase so as to avoid overwriting the portion of the shared file still
+ being read by another file descriptor */
+ application_specific_barrier();
+ }