From d579b10c206a2f675a828f08e836b35958eeb615 Mon Sep 17 00:00:00 2001 From: Sidharth Anupkrishnan Date: Fri, 16 Aug 2019 21:34:16 +0530 Subject: [PATCH] doc: Update documentation for LazyIO Signed-off-by: Sidharth Anupkrishnan --- doc/cephfs/lazyio.rst | 57 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/doc/cephfs/lazyio.rst b/doc/cephfs/lazyio.rst index 6737932a16f..9cd9ae74a59 100644 --- a/doc/cephfs/lazyio.rst +++ b/doc/cephfs/lazyio.rst @@ -19,5 +19,58 @@ LazyIO can be enabled by following ways. - ``ceph_lazyio(...)`` and ``ceph_ll_lazyio(...)`` enable LAZY_IO for file handle in libcephfs. -- ``ioctl(fd, CEPH_IOC_LAZYIO, 1UL)`` enables LAZY_IO for file handle in - ceph-fuse mount. +Using LazyIO +============ + +LazyIO includes two methods ``lazyio_propagate()`` and ``lazyio_synchronize()``. +With LazyIO enabled, writes may not be visble 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 upto 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(); + } -- 2.39.5