[GitHub] eolivelli closed pull request #1571: Write DEFERRED_SYNC docs

[GitBox <gi...@apache.org>]

eolivelli closed pull request #1571: Write DEFERRED_SYNC docs
URL: https://github.com/apache/bookkeeper/pull/1571
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/site/docs/latest/api/ledger-api.md b/site/docs/latest/api/ledger-api.md
index 51a6e847c6..b6cb0f02a9 100644
--- a/site/docs/latest/api/ledger-api.md
+++ b/site/docs/latest/api/ledger-api.md
@@ -560,8 +560,7 @@ Available write flags:
 
 | Flag  | Explanation  | Notes |
 :---------|:------------|:-------
-DEFERRED_SYNC | Writes are acknowledged early, without waiting for
-guarantees of durability | Data will be only written to the OS page cache, without forcing an fsync.
+DEFERRED_SYNC | Writes are acknowledged early, without waiting for guarantees of durability | Data will be only written to the OS page cache, without forcing an fsync.
 
 ```java
 BookKeeper bk = ...;
@@ -800,3 +799,43 @@ bk.newDeleteLedgerOp()
     .execute()
     .get();
 ```
+
+### Relaxing Durability
+
+In BookKeeper by default each write will be acklowledged to the client if and only if it has been persisted durably (fsync called on the file system) by a quorum of bookies.
+In this case the LastAddConfirmed pointer is updated on the writer side, this is the guarantee for the writer that data will not be lost and it will
+be always readable by other clients.
+
+On the client side you can temporary relax this constraint by using the [`DEFERRED_SYNC`](../javadoc/org/apache/bookkeeper/client/api/WriteFlag) Write flag. Using this flag bookies will acknowledge each entry after
+writing the entry to SO buffers without waiting for an fsync.
+In this case the LastAddConfirmed pointer is not advanced to the writer side neither is updated on the reader's side, this is because **there is some chance to lose the entry**.
+Such entries will be still readable using readUnconfirmed() API, but they won't be readable using Long Poll reads or regular read() API.
+
+In order to get guarantees of durability the writer must use explicitly the [force()](../javadoc/org/apache/bookkeeper/client/api/ForceableHandle) API which will return only after all the bookies in the ensemble ackknowledge the call after
+performing an fsync to the disk which is storing the journal.
+This way the LastAddConfirmed pointer is advanced on the writer side and it will be eventually available to the readers.
+
+The *close()* operation on the writer writes on ledger's metadata the current LastAddConfirmed pointer, **it is up to the application to call force() before issuing the close command**.
+In case that you never call explicitly [force()](../javadoc/org/apache/bookkeeper/client/api/ForceableHandle) the LastAddConfirmed will remain unset (-1) on ledger metadata and regular readers won't be able to access data.
+
+
+```java
+BookKeeper bk = ...;
+long ledgerId = ...;
+
+WriteHandle wh = bk.newCreateLedgerOp()
+    .withDigestType(DigestType.CRC32)
+    .withPassword(password)
+    .withEnsembleSize(3)
+    .withWriteQuorumSize(3)
+    .withAckQuorumSize(2)
+    .withWriteFlags(DEFERRED_SYNC)
+    .execute()          // execute the creation op
+    .get();             // wait for the execution to complete
+
+
+wh.force().get();  // wait for fsync, make data available to readers and to the replicator
+
+wh.close(); // seal the ledger
+    
+```


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services