Merge pull request #725 from IntersectMBO/wenkokke/fix-diskio-cost

doc: fix disk I/O complexity of several operators

Author: wenkokke

src/Database/LSMTree.hs

@@ -380,16 +380,16 @@ Run an action with access to a session opened from a session directory.
 If the session directory is empty, a new session is created.
 Otherwise, the session directory is opened as an existing session.
 
-The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+If there are no open tables or cursors when the session terminates, then this disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the open tables in the session.
+The following assumes all tables in the session have the same merge policy:
 
 ['LazyLevelling']:
-    \(O(o \: T \log_T \frac{n}{B})\).
+  \(O(o \: T \log_T \frac{n}{B})\).
 
 The variable \(o\) refers to the number of open tables and cursors in the session.
 
-If the session has any open tables, then 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
-Otherwise, the disk I\/O cost operation is \(O(1)\).
-
 This function is exception-safe for both synchronous and asynchronous exceptions.
 
 It is recommended to use this function instead of 'openSession' and 'closeSession'.
@@ -496,16 +496,16 @@ openSessionIO tracer sessionDir = do
 {- |
 Close a session.
 
-The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+If there are no open tables or cursors in the session, then this disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the tables in the session.
+The following assumes all tables in the session have the same merge policy:
 
 ['LazyLevelling']:
-    \(O(o \: T \log_T \frac{n}{B})\).
+  \(O(o \: T \log_T \frac{n}{B})\).
 
 The variable \(o\) refers to the number of open tables and cursors in the session.
 
-If the session has any open tables, then 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
-Otherwise, this operation takes constant time.
-
 Closing is idempotent, i.e., closing a closed session does nothing.
 All other operations on a closed session will throw an exception.
 -}
@@ -531,7 +531,10 @@ closeSession (Session session) =
 {- |
 Run an action with access to an empty table.
 
-The worst-case disk I\/O complexity of this operation is \(O(1)\).
+The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+
+['LazyLevelling']:
+    \(O(T \log_T \frac{n}{B})\).
 
 This function is exception-safe for both synchronous and asynchronous exceptions.
 
@@ -621,7 +624,10 @@ newTableWith tableConfig (Session session) =
 {- |
 Close a table.
 
-The worst-case disk I\/O complexity of this operation is \(O(T \log_T \frac{n}{B})\).
+The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+
+['LazyLevelling']:
+    \(O(T \log_T \frac{n}{B})\).
 
 Closing is idempotent, i.e., closing a closed table does nothing.
 All other operations on a closed table will throw an exception.

src/Database/LSMTree/Simple.hs

@@ -344,16 +344,16 @@ newtype Session = Session (LSMT.Session IO)
 {- |
 Run an action with access to a session opened from a session directory.
 
-The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+If there are no open tables or cursors when the session terminates, then this disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the open tables in the session.
+The following assumes all tables in the session have the same merge policy:
 
 ['LazyLevelling']:
-    \(O(o \: T \log_T \frac{n}{B})\).
+  \(O(o \: T \log_T \frac{n}{B})\).
 
 The variable \(o\) refers to the number of open tables and cursors in the session.
 
-If the session has any open tables, then 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
-Otherwise, the disk I\/O cost operation is \(O(1)\).
-
 This function is exception-safe for both synchronous and asynchronous exceptions.
 
 It is recommended to use this function instead of 'openSession' and 'closeSession'.
@@ -406,16 +406,16 @@ openSession dir = do
 {- |
 Close a session.
 
-The worst-case disk I\/O complexity of this operation depends on the merge policy of the table:
+If there are no open tables or cursors in the session, then this disk I\/O complexity of this operation is \(O(1)\).
+Otherwise, 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
+Consequently, the worst-case disk I\/O complexity of this operation depends on the merge policy of the tables in the session.
+The following assumes all tables in the session have the same merge policy:
 
 ['LazyLevelling']:
-    \(O(o \: T \log_T \frac{n}{B})\).
+  \(O(o \: T \log_T \frac{n}{B})\).
 
 The variable \(o\) refers to the number of open tables and cursors in the session.
 
-If the session has any open tables, then 'closeTable' is called for each open table and 'closeCursor' is called for each open cursor.
-Otherwise, the disk I\/O cost operation is \(O(1)\).
-
 Closing is idempotent, i.e., closing a closed session does nothing.
 All other operations on a closed session will throw an exception.
 -}