[c++] Refactor metadata and create to respect timestamps

[nguyenv]

Issue and/or context:

#2182

I am refactoring the create and metadata methods in C++ after I noticed issues while working on transitioning the Python SOMADataFrame write path to use clib.DataFrame.

Changes:

• Store read-mode Array or Group that holds metadata values valid as a class memeber

    // Metadata values need to be accessible in write mode as well. When adding
    // or deleting values in the array, instead of closing to update to
    // metadata; then reopening to read the array; and again reopening to
    // restore the array back to write mode, we just store the modifications to
    // this cache
    std::map<std::string, MetadataValue> metadata_;

    // Array associated with metadata_. We need to keep this read-mode array
    // alive in order for the metadata value pointers in the cache to be
    // accessible
    std::shared_ptr<Array> meta_cache_arr_;

• create methods now take in timestamps which indicate when the metadata values for soma_object_type and encoding_version should be written (this is consistent to how it is done in the TileDB-SOMA API) and when the write-mode SOMAObject should be opened
• create methods now only open Array or Group once
• Make soma_object_type, encoding_version, and the current encoding version (1) consts
• Use keystroke saver TimestampRange type
• Test that SOMAObjects are writing and reading metadata correctly with timestamps
• Test that array returned by create can be written to

Notes for Reviewer:

These changes have been pulled out of a larger branch: https://github.com/single-cell-data/TileDB-SOMA/tree/viviannguyen/array-write-path

[codecov]

Codecov Report

Merging #2180 (ca62162) into main (e0e3fa4) will not change coverage.
The diff coverage is n/a.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2180   +/-   ##
=======================================
  Coverage   90.61%   90.61%           
=======================================
  Files          37       37           
  Lines        3900     3900           
=======================================
  Hits         3534     3534           
  Misses        366      366           

Flag	Coverage Δ
python	90.61% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
python_api	90.61% <ø> (ø)
libtiledbsoma	∅ <ø> (∅)

[johnkerl]

This is not associated with any open GitHub issue
@nguyenv for tracking purposes, please create one.

[eddelbuettel]

👍

Looks good to me but is also rather comprehensive so may be prudent to gather another +1 before merging.

[nguyenv]

👍

Looks good to me but is also rather comprehensive so may be prudent to gather another +1 before merging.

Gotcha, will wait for another review.

And I'll try to break these PRs up even more next time 😅

[jp-dark]

This PR looks good to me with the caveat that there were a lot of changes, and I'm not entirely sure I understood the implications of everything. I do have two comments:

1. Storing the metadata in memory without re-syncing after a write may lead to an in memory representation of the metadata that does not match the actual metadata on disk if there was another write. This is fine, so long as we are aware and okay with that. (This could be the case even if we did re-open the array, it's just more likely to get out of sync here.)
2. I added a couple nits about not using or removing brackets around a single line if statement, but there were a lot of other places that the brackets were not used or removed. The convention in the core TileDB library is to always have brackets, but I didn't want to flag all of the instances here if we intentionally have a different convention in this library.

[jp-dark]

If there are other writes that happen simultaneously, this metadata map might not reflect any actual representation that you could obtain (even with time traveling). Are we okay with this?

[nguyenv]

What would be a better way to cache the metadata so that we deal with simulatenous writes correctly?

[jp-dark]

Re-reading the data from disk is safer but slower, so it really just depends on what trade-offs we want to make.

[johnkerl]

@nguyenv what else needs to happen to get this PR merged? Please let me know if/how I can help.

[johnkerl]

Thanks @nguyenv !