Build-To-Use: 4.0.0-5

CBL-5616: Update SG version in docker-compose.yml (#2121)
CBL-6239: Fixed c4doc_getRevisionBody in a 2.x db (#2136)
92fc5cc Make sync work across VV upgrades (#1913)
abe9759 Merge in tag 3.2.0
8009302 Statically link to libstdc++ (#2134)
CBL-6169: DataFile::documentKeys() is not thread-safe (#2132)
CBL-6189: Annotation of thread-safety, filling in the missing ones after the first pass. (#2129)
471e5ec Allow a Timer to destruct itself during its callback (#2124)
b090363 Fixed C4CollectionSpec hash and equality (#2122)
cba409e LogEncoder cleanup (#2130)
cf53ccd Rewritten query translator (#1966)
9f75fab Updated Fleece now that its PR is merged
d6c2091 Update Android NDK even more
47cc9ad Update Jenkins configuration to support C++20
1652943 C++20: use std::ranges, contains() methods, std::size()
f27f8dd Build with C++20

.gitignore

@@ -54,3 +54,4 @@ C/tests/data/imagePrediction/MobileNet.mlmodel
 C/tests/data/faces/OpenFace.mlmodel
 docs/overview/.Ulysses-Settings.plist
 .vimtasks.json
+cmake-build-debug

C/Cpp_include/c4Database.hh

@@ -113,6 +113,9 @@ struct C4Database
 
         CollectionSpec(slice name) : C4CollectionSpec{name, kC4DefaultScopeID} {}
 
+        /// Substitutes "_default" for a null scope, since the two are equivalent.
+        slice effectiveScope() const FLPURE { return scope.buf ? scope : kC4DefaultScopeID; }
+
         // NOLINTEND(google-explicit-constructor)
     };
 
@@ -287,20 +290,26 @@ struct C4Database
 };
 
 // This stuff allows CollectionSpec to be used as a key in an unordered_map or unordered_set:
-static inline bool operator==(const C4CollectionSpec& a, const C4CollectionSpec& b) {
-    return a.name == b.name && a.scope == b.scope;
+static inline bool operator==(const C4Database::CollectionSpec& a, const C4Database::CollectionSpec& b) {
+    return a.name == b.name && a.effectiveScope() == b.effectiveScope();
 }
 
-static inline bool operator!=(const C4CollectionSpec& a, const C4CollectionSpec& b) { return !(a == b); }
+static inline bool operator!=(const C4Database::CollectionSpec& a, const C4Database::CollectionSpec& b) {
+    return !(a == b);
+}
 
 template <>
-struct std::hash<C4CollectionSpec> {
-    std::size_t operator()(C4CollectionSpec const& spec) const {
-        return fleece::slice(spec.name).hash() ^ fleece::slice(spec.scope).hash();
+struct std::hash<C4Database::CollectionSpec> {
+    std::size_t operator()(C4Database::CollectionSpec const& spec) const {
+        return fleece::slice(spec.name).hash() ^ spec.effectiveScope().hash();
     }
 };
 
 template <>
-struct std::hash<C4Database::CollectionSpec> : public std::hash<C4CollectionSpec> {};
+struct std::hash<C4CollectionSpec> {
+    std::size_t operator()(C4Database::CollectionSpec const& spec) const {
+        return std::hash<C4Database::CollectionSpec>{}(spec);
+    }
+};
 
 C4_ASSUME_NONNULL_END

C/c4Base.cc

@@ -53,20 +53,21 @@ bool C4ExpectingExceptions() { return gC4ExpectExceptions > 0; }  // LCOV_EXCL_L
 static string getBuildInfo() {
     static string commit;
 #ifdef COUCHBASE_ENTERPRISE
-    if ( commit.empty() ) { commit = format("%.16s+%.16s", GitCommitEE, GitCommit); }
+    if ( commit.empty() ) { commit = stringprintf("%.16s+%.16s", GitCommitEE, GitCommit); }
     static const char* ee = "EE ";
 #else
-    if ( commit.empty() ) { commit = format("%.16s", GitCommit); }
+    if ( commit.empty() ) { commit = stringprintf("%.16s", GitCommit); }
     static const char* ee = "";
 #endif
 #if LiteCoreOfficial
-    return format("%sbuild number %s, ID %.8s, from commit %s", ee, LiteCoreBuildNum, LiteCoreBuildID, commit.c_str());
+    return stringprintf("%sbuild number %s, ID %.8s, from commit %s", ee, LiteCoreBuildNum, LiteCoreBuildID,
+                        commit.c_str());
 #else
     if ( strcmp(GitBranch, "HEAD") == (0) )
-        return format("%sbuilt from commit %s%s on %s %s", ee, commit.c_str(), GitDirty, __DATE__, __TIME__);
+        return stringprintf("%sbuilt from commit %s%s on %s %s", ee, commit.c_str(), GitDirty, __DATE__, __TIME__);
     else
-        return format("%sbuilt from %s branch, commit %s%s on %s %s", ee, GitBranch, commit.c_str(), GitDirty, __DATE__,
-                      __TIME__);
+        return stringprintf("%sbuilt from %s branch, commit %s%s on %s %s", ee, GitBranch, commit.c_str(), GitDirty,
+                            __DATE__, __TIME__);
 #endif
 }
 
@@ -75,19 +76,19 @@ C4StringResult c4_getBuildInfo() C4API { return toSliceResult(getBuildInfo()); }
 C4StringResult c4_getVersion() C4API {
     string vers;
 #if LiteCoreOfficial
-    vers = format("%s (%s)", LiteCoreVersion, LiteCoreBuildNum);
+    vers = stringprintf("%s (%s)", LiteCoreVersion, LiteCoreBuildNum);
 #else
 #    ifdef COUCHBASE_ENTERPRISE
     static const char* ee     = "-EE";
-    string             commit = format("%.16s+%.16s", GitCommitEE, GitCommit);
+    string             commit = stringprintf("%.16s+%.16s", GitCommitEE, GitCommit);
 #    else
     static const char* ee     = "";
-    string             commit = format("%.16s", GitCommit);
+    string             commit = stringprintf("%.16s", GitCommit);
 #    endif
     if ( strcmp(GitBranch, "master") == (0) || strcmp(GitBranch, "HEAD") == (0) )
-        vers = format("%s%s (%s%.1s)", LiteCoreVersion, ee, commit.c_str(), GitDirty);
+        vers = stringprintf("%s%s (%s%.1s)", LiteCoreVersion, ee, commit.c_str(), GitDirty);
     else
-        vers = format("%s%s (%s:%s%.1s)", LiteCoreVersion, ee, GitBranch, commit.c_str(), GitDirty);
+        vers = stringprintf("%s%s (%s:%s%.1s)", LiteCoreVersion, ee, GitBranch, commit.c_str(), GitDirty);
 #endif
     return toSliceResult(vers);
 }

C/c4Error.cc

@@ -83,7 +83,7 @@ namespace litecore {
             ErrorInfo info;
             if ( format && *format ) {
                 try {
-                    info.message = vformat(format, args);
+                    info.message = vstringprintf(format, args);
                 } catch ( ... ) {}
             }
             return makeError(domain, code, std::move(info), skipStackFrames + 1);
@@ -214,7 +214,7 @@ namespace litecore {
     if ( format ) {
         va_list args;
         va_start(args, format);
-        message = vformat(format, args);
+        message = vstringprintf(format, args);
         va_end(args);
     }
     error{error::Domain(domain), code, message}._throw(1);

C/include/c4Base.h

@@ -220,8 +220,10 @@ CBL_CORE_API C4Socket* C4NULLABLE          c4socket_retain(C4Socket* C4NULLABLE)
 
 static inline void c4cert_release(C4Cert* C4NULLABLE r) C4API { c4base_release(r); }
 
+/** \note This function is thread-safe. */
 static inline void c4coll_release(C4Collection* C4NULLABLE r) C4API { c4base_release(r); }
 
+/** \note This function is thread-safe. */
 static inline void c4db_release(C4Database* C4NULLABLE r) C4API { c4base_release(r); }
 
 static inline void c4index_release(C4Index* C4NULLABLE i) C4API { c4base_release(i); }
@@ -230,18 +232,25 @@ static inline void c4indexupdater_release(C4IndexUpdater* C4NULLABLE u) C4API {
 
 static inline void c4keypair_release(C4KeyPair* C4NULLABLE r) C4API { c4base_release(r); }
 
+/** \note This function is thread-safe. */
 static inline void c4query_release(C4Query* C4NULLABLE r) C4API { c4base_release(r); }
 
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4doc_release(C4Document* C4NULLABLE) C4API;
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4queryenum_release(C4QueryEnumerator* C4NULLABLE) C4API;
 CBL_CORE_API void c4socket_release(C4Socket* C4NULLABLE) C4API;
 
 // These types are _not_ ref-counted, but must be freed after use:
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4dbobs_free(C4CollectionObserver* C4NULLABLE) C4API;
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4docobs_free(C4DocumentObserver* C4NULLABLE) C4API;
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4enum_free(C4DocEnumerator* C4NULLABLE) C4API;
 /** Closes and disposes a listener. */
 CBL_CORE_API void c4listener_free(C4Listener* C4NULLABLE) C4API;
+/** \note This function is thread-safe. */
 CBL_CORE_API void c4queryobs_free(C4QueryObserver* C4NULLABLE) C4API;
 /** Frees the storage occupied by a raw document. */
 CBL_CORE_API void c4raw_free(C4RawDocument* C4NULLABLE) C4API;
@@ -250,11 +259,13 @@ CBL_CORE_API void c4raw_free(C4RawDocument* C4NULLABLE) C4API;
         it will keep going. If you need the replicator to stop, call \ref c4repl_stop first.
         \note This function is thread-safe. */
 CBL_CORE_API void c4repl_free(C4Replicator* C4NULLABLE) C4API;
-/** Closes a read-stream. (A NULL parameter is allowed.) */
+/** Closes a read-stream. (A NULL parameter is allowed.) 
+    \note After close, the ReadStream is deleted. */
 CBL_CORE_API void c4stream_close(C4ReadStream* C4NULLABLE) C4API;
 /** Closes a blob write-stream. If c4stream_install was not already called (or was called but
         failed), the temporary file will be deleted without adding the blob to the store.
-        (A NULL parameter is allowed, and is a no-op.) */
+        (A NULL parameter is allowed, and is a no-op.) 
+        \note After close, the WriteStream is deleted. */
 CBL_CORE_API void c4stream_closeWriter(C4WriteStream* C4NULLABLE) C4API;
 
 
@@ -305,7 +316,8 @@ CBL_CORE_API C4Timestamp c4_now(void) C4API;
 
 /** Wiring call for platforms without discoverable temporary directories.  Simply sets the SQLite
     temp directory so that it can write its temporary files without error.  Several platforms need
-    to do this, but not all need to use this API.  
+    to do this, but not all need to use this API.
+    \note This function is not thread-safe. 
     @param path The path to a writable directory for temporary files for SQLite
     @param err  If an error happens (e.g. it is an error to call this function twice), this parameter
                 records it.

C/include/c4BlobStore.h

@@ -125,11 +125,8 @@ NODISCARD CBL_CORE_API bool c4blob_delete(C4BlobStore*, C4BlobKey, C4Error* C4NU
 /** \name Streamed Reads
         @{ */
 
-/* NOTE: These functions are thread-safe in the same manner as described in the previous
-       section, with the additional restriction that a stream cannot be called concurrently on
-       multiple threads. */
-
-/** Opens a blob for reading, as a random-access byte stream. */
+/** Opens a blob for reading, as a random-access byte stream.
+    \note This function is thread-safe. */
 NODISCARD CBL_CORE_API C4ReadStream* c4blob_openReadStream(C4BlobStore*, C4BlobKey, C4Error* C4NULLABLE) C4API;
 
 /** Reads from an open stream.
@@ -142,7 +139,8 @@ NODISCARD CBL_CORE_API C4ReadStream* c4blob_openReadStream(C4BlobStore*, C4BlobK
 NODISCARD CBL_CORE_API size_t c4stream_read(C4ReadStream* stream, void* buffer, size_t maxBytesToRead,
                                             C4Error* C4NULLABLE error) C4API;
 
-/** Returns the exact length in bytes of the stream. */
+/** Returns the exact length in bytes of the stream. 
+    \note This function is thread-safe. */
 CBL_CORE_API int64_t c4stream_getLength(C4ReadStream*, C4Error* C4NULLABLE) C4API;
 
 /** Moves to a random location in the stream; the next c4stream_read call will read from that
@@ -156,13 +154,10 @@ NODISCARD CBL_CORE_API bool c4stream_seek(C4ReadStream*, uint64_t position, C4Er
 /** \name Streamed Writes
         @{ */
 
-/* NOTE: These functions are thread-safe in the same manner as described in the previous
-       section, with the additional restriction that a stream cannot be called concurrently on
-       multiple threads. */
-
 /** Opens a write stream for creating a new blob. You should then call c4stream_write to
         write the data, ending with c4stream_install to compute the blob's key and add it to
-        the store, and then c4stream_closeWriter. */
+        the store, and then c4stream_closeWriter. 
+        \note This function is thread-safe. */
 NODISCARD CBL_CORE_API C4WriteStream* c4blob_openWriteStream(C4BlobStore*, C4Error* C4NULLABLE) C4API;
 
 /** Writes data to a stream. 

C/include/c4Database.h

@@ -54,6 +54,7 @@ CBL_CORE_API void c4_setExtensionPath(C4String path) C4API;
  * of the extension and the path in which it is supposed to reside.  It makes an attempt
  * to only check things that have the possibility of being corrected by the user (i.e.
  * if there is a bug in the extension and it cannot load functionally that won't be caught)
+ * \note This function is not thread-safe.
  * @param name The name of the extension (corresponds to the filename
  *             without the extension or "lib" prefix)
  * @param extensionPath The path in which the extension should be found
@@ -74,13 +75,14 @@ CBL_CORE_API bool c4_enableExtension(C4String name, C4String extensionPath, C4Er
 CBL_CORE_API bool c4db_exists(C4String name, C4String inDirectory) C4API;
 
 
-/** Opens a database given its name (without the ".cblite2" extension) and directory. */
+/** Opens a database given its name (without the ".cblite2" extension) and directory.
+    \note This function is thread-safe. */
 NODISCARD CBL_CORE_API C4Database* c4db_openNamed(C4String name, const C4DatabaseConfig2* config,
                                                   C4Error* C4NULLABLE outError) C4API;
 
 /** Opens a new handle to the same database file as `db`.
         The new connection is completely independent and can be used on another thread. 
-    \note The caller must use a lock for Database when this function is called. */
+        \note This function is thread-safe. */
 NODISCARD CBL_CORE_API C4Database* c4db_openAgain(C4Database* db, C4Error* C4NULLABLE outError) C4API;
 
 /** Copies a prebuilt database from the given source path and places it in the destination
@@ -103,17 +105,20 @@ NODISCARD CBL_CORE_API bool c4db_close(C4Database* C4NULLABLE database, C4Error*
 
 /** Closes the database and deletes the file/bundle. Does not free the handle, although any
         operation other than c4db_release() will fail with an error. 
-        All C4Databases at that path must be closed first or an error will result.*/
+        All C4Databases at that path must be closed first or an error will result.
+        \note This function is thread-safe. */
 NODISCARD CBL_CORE_API bool c4db_delete(C4Database* database, C4Error* C4NULLABLE outError) C4API;
 
 /** Deletes the file(s) for the database with the given name in the given directory.
         All C4Databases at that path must be closed first or an error will result.
-        Returns false, with no error, if the database doesn't exist. */
+        Returns false, with no error, if the database doesn't exist.
+        \note This function is thread-safe. */
 NODISCARD CBL_CORE_API bool c4db_deleteNamed(C4String dbName, C4String inDirectory, C4Error* C4NULLABLE outError) C4API;
 
 
-/** Changes a database's encryption key (removing encryption if it's NULL.) 
-    All C4Databases at that path must be closed first or an error will result.*/
+/** Changes a database's encryption key (removing encryption if it's NULL.)
+    \note The caller must use a lock for Database when this function is called.
+    \note All other C4Databases at that path must be closed first or an error will result.*/
 NODISCARD CBL_CORE_API bool c4db_rekey(C4Database* database, const C4EncryptionKey* C4NULLABLE newKey,
                                        C4Error* C4NULLABLE outError) C4API;
 

C/include/c4DatabaseTypes.h

@@ -31,13 +31,14 @@ C4API_BEGIN_DECLS
 
 /** Boolean options for C4DatabaseConfig. */
 typedef C4_OPTIONS(uint32_t, C4DatabaseFlags){
-        kC4DB_Create          = 0x01,  ///< Create the file if it doesn't exist
-        kC4DB_ReadOnly        = 0x02,  ///< Open file read-only
-        kC4DB_AutoCompact     = 0x04,  ///< Enable auto-compaction [UNIMPLEMENTED]
-        kC4DB_VersionVectors  = 0x08,  ///< Upgrade DB to version vectors instead of rev trees
-        kC4DB_NoUpgrade       = 0x20,  ///< Disable upgrading an older-version database
-        kC4DB_NonObservable   = 0x40,  ///< Disable database/collection observers, for slightly faster writes
-        kC4DB_FakeVectorClock = 0x80,  ///< Use counters instead of timestamps in version vectors (TESTS ONLY)
+        kC4DB_Create          = 0x01,    ///< Create the file if it doesn't exist
+        kC4DB_ReadOnly        = 0x02,    ///< Open file read-only
+        kC4DB_AutoCompact     = 0x04,    ///< Enable auto-compaction [UNIMPLEMENTED]
+        kC4DB_VersionVectors  = 0x08,    ///< Upgrade DB to version vectors instead of rev trees
+        kC4DB_NoUpgrade       = 0x20,    ///< Disable upgrading an older-version database
+        kC4DB_NonObservable   = 0x40,    ///< Disable database/collection observers, for slightly faster writes
+        kC4DB_DiskSyncFull    = 0x80,    ///< Flush to disk after each transaction
+        kC4DB_FakeVectorClock = 0x0100,  ///< Use counters instead of timestamps in version vectors (TESTS ONLY)
 };
 
 

C/include/c4DocumentTypes.h

@@ -51,7 +51,6 @@ typedef C4_ENUM(uint8_t, C4DocContentLevel){
         kDocGetMetadata,    ///< Only get revID and flags
         kDocGetCurrentRev,  ///< Get current revision body but not other revisions/remotes
         kDocGetAll,         ///< Get everything
-        kDocGetUpgraded,    ///< Get everything, upgrade to latest format (version vectors)
 };                          // Note: Same as litecore::ContentOption
 
 // Ignore warning about not initializing members, it must be this way to be C-compatible

C/include/c4Error.h

@@ -195,7 +195,8 @@ static constexpr C4Error kC4NoError = {};
 // C4Error C API:
 
 
-/** Returns an error message describing a C4Error. Remember to free the result. */
+/** Returns an error message describing a C4Error. Remember to free the result. 
+    \note This function is thread-safe. */
 CBL_CORE_API FLStringResult c4error_getMessage(C4Error error) C4API;
 
 /** Returns a description of an error, including the domain and code as well as the message.

C/include/c4Query.h

@@ -95,18 +95,21 @@ CBL_CORE_API C4StringResult c4query_fullTextMatched(C4Query* query, const C4Full
                                                     C4Error* C4NULLABLE outError) C4API;
 
 /** Advances a query enumerator to the next row, populating its fields.
-        Returns true on success, false at the end of enumeration or on error. */
+        \note The caller must use a lock for QueryEnumerator  when this function is called.
+        @return true on success, false at the end of enumeration or on error. */
 NODISCARD CBL_CORE_API bool c4queryenum_next(C4QueryEnumerator* e, C4Error* C4NULLABLE outError) C4API;
 
 /** Returns the total number of rows in the query, if known.
         Not all query enumerators may support this (but the current implementation does.)
+        \note The caller must use a lock for QueryEnumerator  when this function is called.
         @param e  The query enumerator
         @param outError  On failure, an error will be stored here (probably kC4ErrorUnsupported.)
         @return  The number of rows, or -1 on failure. */
 NODISCARD CBL_CORE_API int64_t c4queryenum_getRowCount(C4QueryEnumerator* e, C4Error* C4NULLABLE outError) C4API;
 
 /** Jumps to a specific row. Not all query enumerators may support this (but the current
         implementation does.)
+        \note The caller must use a lock for QueryEnumerator  when this function is called.
         @param e  The query enumerator
         @param rowIndex  The number of the row, starting at 0, or -1 to restart before first row
         @param outError  On failure, an error will be stored here (probably kC4ErrorUnsupported.)

C/include/c4Replicator.h

@@ -30,6 +30,7 @@ NODISCARD CBL_CORE_API bool c4repl_isValidRemote(C4Address remoteAddress, C4Stri
 
 /** A simple URL parser that populates a C4Address from a URL string.
         The fields of the address will point inside the url string.
+        \note This function is thread-safe.
         @param url  The URL to be parsed.
         @param address  On sucess, the fields of the struct this points to will be populated with
                         the address components. This that are slices will point into the