The documentation is outdated

[xJonathanLEI]

The library works great, but the documentation in README.MD is horribly outdated. The example code is simply broken. Takes a while for a beginner to start making transactions.

[KrzysFR]

Sorry about the state of the documentation. The project was archived in 2015 when Apple acquired fdb, and all ongoing projects were canceled. I haven't had a lot of time to dedicate to the documentation since it has been restarted last year.

I created a new GitHub Project to start tracking future progress on a real documentation.

Could you tell me what exactly is broken in the sample so that I can at least fix it?

[xJonathanLEI]

Thanks for the reply. So Apple basically killed fdb...

The example code doesn't compile. For example:

var location = await db.Directory.CreateOrOpenAsync("Test", cancel);

This line is broken as CreateOrOpenAsync() doesn't accept a string and a cancellation token.

Another example:

The library requires a call to Fdb.Start() before doing anything to the database. That wasn't documented in README.MD or included in the sample code.

I just saw the FoundationDB.Samples project and the code inside should work just fine. But I guess new users tend to look at README.MD first.

Thanks for your effort in maintaining the library. I'd love to help out but since I'm new to fdb I doubt I can make any meaningful contributions lol.

[KrzysFR]

Yes you are right, the recent refactoring of the Directory Layer broke the readme (I had to update our codebase due to the same change).

You can contribute by pointing out things that are missing or that are hard to understand :)

[KrzysFR]

Most the API related to directory subspaces has been changed recently, sooo most of the documentation needs to be updated anyway :(

All the samples in the project have been updated to the new API, but there is still the need for some documentation that explains the intended uses of directory location and subspaces, and the best practices to write safe and efficient layers (especially given the restrictions when using cached directory subspaces).

[sandtreader]

Struggling with the same thing, I'm afraid, particularly around the Directory layer...

First a sanity check - is the code that's in Nuget (6.2.0-preview) derived from 'master' branch? I couldn't see any branches or tags that would indicate otherwise, but errors are making me doubt it.

As @xJonathanLEI reported, the code in the readme to create a subspace doesn't compile:

var location = await db.Directory.CreateOrOpenAsync("Test", cancel);

But neither does the (rather nice!) db.Root-based version in the sample code:

this.Subspace = await db.ReadWriteAsync(tr => db.Root["Samples"]"MessageQueueTest"].CreateOrOpenAsync(tr), ct);

Error: 'IFdbDatabase' does not contain a definition for 'Root' ...

The signature in the 'master' code (iFdbDirectory.cs) is

Task<FdbDirectorySubspace> CreateOrOpenAsync(IFdbTransaction trans, FdbPath subPath);

But I can't create an FdbPath in the Nuget version.

So TL;DR: What's the correct way to create a subspace in the version 6.2 in Nuget? :-)

Happy to try to fix up at least the README if we can work out the right answer!

Many thanks

Paul

[sandtreader]

OK, some progress - I've found there is a 5.2.1-preview2 available in Nuget and a matching tag here, so:

<PackageReference Include="FoundationDB.Client" Version="5.2.1-preview2" />

and this means this version (from the 5.2.1 samples) now compiles:

        this.subspace = await db.ReadWriteAsync(
          tr => db.Directory.CreateOrOpenAsync(tr,
                                              new [] { "foo", "bar" }), ct);

However I now get a runtime abort with REMOVED FDB API FUNCTION - I'm guessing that's coming from the foundationdb-client library itself? I'm building 6.3.19 - I'm assuming your versions follow the FDB ones, so it looks like I'd have to back that off to 5.2 as well...

... which is possible, but a solution for 6.2 would be much nicer, obviously!

Thanks again

[KrzysFR]

Sorry about that, yes the nuget package is outdated and is before the change in the subspace API.

We always build from source in our applications, so we did not need the nuget packages to be up to date. I'll try to release a newer version of the packages and tools soon.

The current usage pattern is to create an FdbDirectorySubspaceLocation from db.Root which represents a list of path (basically a list of path segments). This can be cached or stored in a static variable somewhere. Inside a transaction, you call the location.Resolve(tr) to get an actual subspace instance, which is only valid inside the transaction. Any attempt to use it outside will fail. The resolve method will internally try to look-up in a cache, while at the same time adding a deferred value check that will fail the transaction during commit if it realizes that the directory was changed by another process.

This pattern of having a "Resolve" method that must be called within a transaction is the new caching pattern for all layers (the Directory Layer is one of them).

[sandtreader]

Thanks Cristophe!

I see the 7.0.0-preview1 is up on nuget now - I'll try it.

Would it be possible to tag the repo for 6.2.0-preview1 so if people do use that they can find the right source version? I think it would be here:

https://github.com/Doxense/foundationdb-dotnet-client/tree/1e0c453f6a24276280c869cc92af86b2c1bc5d5c

I like the subspace caching! I was wondering about the performance hit of creating them.

Kind regards

Paul

[KrzysFR]

I have published updated nuget packages and created a new release with the tools binaires (win64 .NET 5.0)

• https://www.nuget.org/packages/FoundationDB.Client/7.0.0-preview1
• https://github.com/Doxense/foundationdb-dotnet-client/releases/tag/7.0.0-preview1

This is still marked as "preview", because even though it has version 7.0, I still haven't included all API changes from fdb 7.x in the binding.

Though it is build from the exact same branch as what we use in production (though we build from source and do not use the nuget package directly)

[KrzysFR]

Would it be possible to tag the repo for 6.2.0-preview1 so if people do use that they can find the right source version? I think it would be here:

Sure, but I think the only people who used it before are building from source (with some customization).

I like the subspace caching! I was wondering about the performance hit of creating them.

That's the main reason for the complete redesign of the API. We use layers extensively, and usually all intermixed together in the same transaction, so caching is a real issue that must be handled at the lowest possible level. Right now the deferred value checks are emulated at the binding level, as a compromise, so there is still a bit of overhead.

The new caching API is expected to be able to be composable, so if you have written a layer that use caching internally (for example metadata of a pseudo-table or document collection) then this layer must also interact with the Directory Layer which has its own cache!