Azure-docs: Update API documentation to clarify which APIs cache data, memory implications & relevant ReplicatorConfig settings

[MedAnd]

Update API documentation to clarify which APIs cache data, memory implications & relevant ReplicatorConfig settings as per this request: https://github.com/Azure/service-fabric-issues/issues/1427

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 81cce417-df6e-bbac-5083-9e48f5efd6b2
• Version Independent ID: e713be8d-2f15-11c6-4e85-32de85e1cc3a
• Content: Guidelines & Recommendations for Reliable Collections in Azure Service Fabric
• Content Source: articles/service-fabric/service-fabric-reliable-services-reliable-collections-guidelines.md
• Service: service-fabric
• GitHub Login: @TylerMSFT
• Microsoft Alias: twhitney

[mimckitt]

Thanks for the feedback! I have assigned the issue to the content author to investigate further and update the document as appropriate.

CC @aljo-microsoft @masnider

[aljo-microsoft]

@MedAnd
API documentation is here for Reliable Collections:
https://docs.microsoft.com/dotnet/api/microsoft.servicefabric.data.collections?view=azure-dotnet

[MedAnd]

@aljo-microsoft - for full details please refer to production support request ID 119012524000319 which we are still working through with @zuhairp assistance.

In summary this request is to update the public documentation for all ReliableDictionary APIs to clarify the affect on memory of calling different Reliable Collection methods.

For example:

• Does TryGetValueAsync(ITransaction, TKey) cache the TValue of a TKey in memory?
• For how long is the TValue value cached by default?
• Under high load scenarios how can any default caching time be reduced, are there any settings to control the caching & cache invalidation/clean-up behavior?
• Does ContainsKeyAsync(ITransaction, TKey) cache the TValue of a TKey in memory etc?
• Does CreateKeyEnumerableAsync(ITransaction) cache the TValue of a TKey in memory or is each TKey/TValue pair loaded from storage per iteration and never cached by default?

PS. Hope the above makes sense?

[aljo-microsoft]

@preethasubbarayalu

Could you provide content for this question?

[MedAnd]

Friendly ping... any update 😎 ?

[Nickomang]

@MedAnd, We've assigned one of our SMEs to take a look at augmenting the doc and hope to have another update soon.

[ashishnegi]

@MedAnd

Does TryGetValueAsync(ITransaction, TKey) cache the TValue of a TKey in memory?

Yes

Does ContainsKeyAsync(ITransaction, TKey) cache the TValue of a TKey in memory etc?

All the keys are in memory always. Value are removed from memory depending upon sweep policy.
In ContainsKeyAsync, TValue is not loaded so it is not cached.

Does CreateKeyEnumerableAsync(ITransaction) cache the TValue of a TKey in memory or is each TKey/TValue pair loaded from storage per iteration and never cached by default?

CreateKeyEnumerableAsync only iterates over keys, which are always in memory in today's implementation. So, values are not loaded in this API calls.
See tstore.cs CreateKeyEnumerableAsync, especially ReadMode.Off which means don't read value.

In CreateEnumerableAsync which returns key and values, we only read values but don't cache it, otherwise, we will have to cache the whole db as we are enumerating over all keys/values. See, Readmode.ReadValue at tstore.cs CreateEnumerableAsync

The third enum of ReadMode is CacheResult which is used when you read only one key as here

[Nickomang]

@MedAnd, I believe the above response should satisfy the question.

please-close

[MedAnd]

@Nickomang - will the above clarification be expanded & included in the official Service Fabric documentation & best practices?