Add miscelaneous haddock doc improvements to the normal API #10
Conversation
There was a problem hiding this comment.
Left some comments about additions to the documentation.
To model these additional requirements, the model should have access to some "global state". For example, creating new sessions in the same folder should probably result in an exception, but the only way to model that is if we globally know which sessions are currently opened in which folders. See https://github.com/input-output-hk/lsm-tree/pull/4/files#diff-4c5ac7d802bb3e12d031dd04443db91f1a0e4a2f8115c0e3ff469887aba9d750
| -- parts. A table handle is the object/reference by which an in-use LSM table | ||
| -- will be operated upon. In our API it identifies a single mutable instance of | ||
| -- parts. A table handle is the object\/reference by which an in-use LSM table | ||
| -- will be operated upon. In this API it identifies a single mutable instance of | ||
| -- an LSM table. The multiple-handles feature allows for there to may be many | ||
| -- such instances in use at once. | ||
| type TableHandle :: (Type -> Type) -> Type -> Type -> Type -> Type |
There was a problem hiding this comment.
Addition:
- An operation on a table handle should throw an exception if the table handle is closed.
- Closing a table handle should be idempotent IMO
Regarding sessions:
- Once a session is closed, any table handles related to that session should be closed as well.
- Using a session once it is closed, for example in
neworopen, should result in an exception - Opening two sessions in the same folder should probably also result in an exception. We might otherwise get name clashes for files. A session should ensure that file names are unique within that session, but when two sessions are open in the same folder, then both sessions might create files of the same name
| @@ -272,7 +294,7 @@ snapshot :: | |||
| -> m () | |||
| snapshot = undefined | |||
|
|
|||
| -- | Open a table through a snapshot, returning a new table handle. | |||
| -- | Open a table from a named snapshot, returning a new table handle. | |||
There was a problem hiding this comment.
Addition:
- Opening a snapshot that doesn't exist should result in an exception.
- If we try to open a snapshot but the types of keys+values+blobs are not as expected, then an exception should be thrown. For example, if a snapshot was created from a
TableHandle m Int Int Int, but we open it asTableHandle m Bool Bool Bool, we get an exception
There was a problem hiding this comment.
f we try to open a snapshot but the types of keys+values+blobs are not as expected
How that can be enforced? E.g. Typeable is not stable value (if type is moved to the different module, it will change).
There was a problem hiding this comment.
We could use some other type of tag that could be written to disk, like a custom class
The alternative would be that a user gets a encoder/decoder error as soon as they try to manipulate/query a table with the wrong type
I don't think it's worth modelling that. All model sessions can live independently of each other. I.e. the ... EDIT except if you want to make lockstep which opens/closes sessions often/all-the-time; but that is unrealistic usage pattern. |
I suppose it's also fine if we do the extensive modelling only for the lockstep tests, and focus on the table model here instead. The latter is where all the interesting stuff happens anyway, and session/snapshot/handle administration is fairly straightforward. My plan would not be to test opening/closing sessions all the time, but IMO it still makes sense to test a few use cases related to sessions/snapshots/handles administration, for example:
|
In particular, discuss snapshots, duplicates, resource management and concurrency.
dcoutts
force-pushed
the
dcoutts/haddocks
branch
from
af50f17
to
ff3853d
Compare
It mangles the haddock sections. See haskell/stylish-haskell#466 And fix one whitespace issue stylish-haskell found.
In particular, discuss snapshots and duplicates: durability and persistent data structures.