Skip to content

Commit 6c1edf3

Browse files
rjagiewichrjagiewich
authored
Merge pull request #11747 from mcoskun/mc_dividecollections
Mc dividecollections
2 parents 2e7d4cb + c63099e commit 6c1edf3

5 files changed

+233
-124
lines changed

‎articles/service-fabric/TOC.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,19 @@
5050
#### Concepts
5151
##### [Reliable Services lifecycle - C#](service-fabric-reliable-services-lifecycle.md)
5252
##### [Reliable Services lifecycle - Java](service-fabric-reliable-services-lifecycle-java.md)
53+
54+
#### Reliable Collections
5355
##### [Reliable Collections](service-fabric-reliable-services-reliable-collections.md)
56+
##### [Reliable Collection guidelines & recommendations](service-fabric-reliable-services-reliable-collections-guidelines.md)
57+
##### [Working with Reliable Collections](service-fabric-work-with-reliable-collections.md)
58+
##### [Transactions and locks](service-fabric-reliable-services-reliable-collections-transactions-locks.md)
59+
##### [Reliable State Manager and Reliable Collection internals](service-fabric-reliable-services-reliable-collections-internals.md)
5460

5561
#### Get started
5662
##### [C# on Windows](service-fabric-reliable-services-quick-start.md)
5763
##### [Java on Linux](service-fabric-reliable-services-quick-start-java.md)
5864

5965
#### Reliable Services lifecycle
60-
#### [Use Reliable Collections](service-fabric-work-with-reliable-collections.md)
6166
#### [Configure](service-fabric-reliable-services-configuration.md)
6267
#### [Send notifications](service-fabric-reliable-services-notifications.md)
6368
#### [Backup and restore](service-fabric-reliable-services-backup-restore.md)

‎articles/service-fabric/service-fabric-reliable-services-reliable-collections-guidelines.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Guidelines & Recommendations for Reliable Collections in Azure Service Fabric | Microsoft Docs
3+
description: Guidelines and Recommendations for using Service Fabric Reliable Collections
4+
services: service-fabric
5+
documentationcenter: .net
6+
author: mcoskun
7+
manager: timlt
8+
editor: masnider,rajak
9+
10+
ms.assetid: 62857523-604b-434e-bd1c-2141ea4b00d1
11+
ms.service: service-fabric
12+
ms.devlang: dotnet
13+
ms.topic: article
14+
ms.tgt_pltfrm: na
15+
ms.workload: required
16+
ms.date: 5/3/2017
17+
ms.author: mcoskun
18+
19+
---
20+
# Guidelines and recommendations for Reliable Collections in Azure Service Fabric
21+
This section provides guidelines for using Reliable State Manager and Reliable Collections. The goal is to help users avoid common pitfalls.
22+
23+
The guidelines are organized as simple recommendations prefixed with the terms *Do*, *Consider*, *Avoid* and *Do not*.
24+
25+
* Do not modify an object of custom type returned by read operations (for example, `TryPeekAsync` or `TryGetValueAsync`). Reliable Collections, just like Concurrent Collections, return a reference to the objects and not a copy.
26+
* Do deep copy the returned object of a custom type before modifying it. Since structs and built-in types are pass-by-value, you do not need to do a deep copy on them.
27+
* Do not use `TimeSpan.MaxValue` for time-outs. Time-outs should be used to detect deadlocks.
28+
* Do not use a transaction after it has been committed, aborted, or disposed.
29+
* Do not use an enumeration outside of the transaction scope it was created in.
30+
* Do not create a transaction within another transaction’s `using` statement because it can cause deadlocks.
31+
* Do ensure that your `IComparable<TKey>` implementation is correct. The system takes dependency on `IComparable<TKey>` for merging checkpoints and rows.
32+
* Do use Update lock when reading an item with an intention to update it to prevent a certain class of deadlocks.
33+
* Consider keeping your items (for example, TKey + TValue for Reliable Dictionary) below 80 KBytes: smaller the better. This reduces the amount of Large Object Heap usage as well as disk and network IO requirements. Often, it reduces replicating duplicate data when only one small part of the value is being updated. Common way to achieve this in Reliable Dictionary, is to break your rows in to multiple rows.
34+
* Consider using backup and restore functionality to have disaster recovery.
35+
* Avoid mixing single entity operations and multi-entity operations (e.g `GetCountAsync`, `CreateEnumerableAsync`) in the same transaction due to the different isolation levels.
36+
* Do handle InvalidOperationException. User transactions can be aborted by the system for variety of reasons. For example, when the Reliable State Manager is changing its role out of Primary or when a long-running transaction is blocking truncation of the transactional log. In such cases, user may receive InvalidOperationException indicating that their transaction has already been terminated. Assuming, the termination of the transaction was not requested by the user, best way to handle this exception is to dispose the transaction, check if the cancellation token has been signaled (or the role of the replica has been changed), and if not create a new transaction and retry.
37+
38+
Here are some things to keep in mind:
39+
40+
* The default time-out is four seconds for all the Reliable Collection APIs. Most users should use the default time-out.
41+
* The default cancellation token is `CancellationToken.None` in all Reliable Collections APIs.
42+
* The key type parameter (*TKey*) for a Reliable Dictionary must correctly implement `GetHashCode()` and `Equals()`. Keys must be immutable.
43+
* To achieve high availability for the Reliable Collections, each service should have at least a target and minimum replica set size of 3.
44+
* Read operations on the secondary may read versions that are not quorum committed.
45+
This means that a version of data that is read from a single secondary might be false progressed.
46+
Reads from Primary are always stable: can never be false progressed.
47+
48+
### Next steps
49+
* [Working with Reliable Collections](service-fabric-work-with-reliable-collections.md)
50+
* [Transactions and Locks](service-fabric-reliable-services-reliable-collections-transactions-locks.md)
51+
* [Reliable State Manager and Collection Internals](service-fabric-reliable-services-reliable-collections-internals.md)
52+
* Managing Data
53+
* [Backup and Restore](service-fabric-reliable-services-backup-restore.md)
54+
* [Notifications](service-fabric-reliable-services-notifications.md)
55+
* [Serialization and Upgrade](service-fabric-application-upgrade-data-serialization.md)
56+
* [Reliable State Manager configuration](service-fabric-reliable-services-configuration.md)
57+
(service-fabric-reliable-services-backup-restore.md)
58+
* Others
59+
* [Reliable Services quick start](service-fabric-reliable-services-quick-start.md)
60+
* [Developer reference for Reliable Collections](https://msdn.microsoft.com/library/azure/microsoft.servicefabric.data.collections.aspx)

‎articles/service-fabric/service-fabric-reliable-services-reliable-collections-internals.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Azure Service Fabric Reliable State Manager and Reliable Collection internals | Microsoft Docs
3+
description: Deep dive on reliable collection concepts and design in Azure Service Fabric.
4+
services: service-fabric
5+
documentationcenter: .net
6+
author: mcoskun
7+
manager: timlt
8+
editor: rajak
9+
10+
ms.assetid: 62857523-604b-434e-bd1c-2141ea4b00d1
11+
ms.service: service-fabric
12+
ms.devlang: dotnet
13+
ms.topic: article
14+
ms.tgt_pltfrm: na
15+
ms.workload: required
16+
ms.date: 5/1/2017
17+
ms.author: mcoskun
18+
19+
---
20+
21+
# Azure Service Fabric Reliable State Manager and Reliable Collection internals
22+
This document delves inside Reliable State Manager and Reliable Collections to see how core components work behind the scenes.
23+
24+
> [!NOTE]
25+
> This document is work in-progress. Add comments to this article to tell us what topic you would like to learn more about.
26+
>
27+
28+
## Local persistence model: log and checkpoint
29+
The Reliable State Manager and Reliable Collections follow a persistence model that is called Log and Checkpoint.
30+
In this model, each state change is logged on disk first and then applied in memory.
31+
The complete state itself is persisted only occasionally (a.k.a. Checkpoint).
32+
The benefit is that deltas are turned into sequential append-only writes on disk for improved performance.
33+
34+
To better understand the Log and Checkpoint model, let’s first look at the infinite disk scenario.
35+
The Reliable State Manager logs every operation before it is replicated.
36+
Logging allows the Reliable Collections to apply the operation only in memory.
37+
Since logs are persisted, even when the replica fails and needs to be restarted, the Reliable State Manager has enough information in its log to replay all the operations the replica has lost.
38+
As the disk is infinite, log records never need to be removed and the Reliable Collection needs to manage only the in-memory state.
39+
40+
Now let’s look at the finite disk scenario.
41+
As log records accumulate, the Reliable State Manager will run out of disk space.
42+
Before that happens, the Reliable State Manager needs to truncate its log to make room for the newer records.
43+
Reliable State Manager requests the Reliable Collections to checkpoint their in-memory state to disk.
44+
At this point, the Reliable Collections' would persist its in-memory state.
45+
Once the Reliable Collections complete their checkpoints, the Reliable State Manager can truncate the log to free up disk space.
46+
When the replica needs to be restarted, Reliable Collections recover their checkpointed state, and the Reliable State Manager recovers and plays back all the state changes that occurred since the last checkpoint.
47+
48+
Another value add of checkpointing is that it improves recovery times in common scenarios.
49+
Log contains all operations that have happened since the last checkpoint.
50+
So it may include multiple versions of an item like multiple values for a given row in Reliable Dictionary.
51+
In contrast, a Reliable Collection checkpoints only the latest version of each value for a key.
52+
53+
## Next steps
54+
* [Transactions and Locks](service-fabric-reliable-services-reliable-collections-transactions-locks.md)
55+

‎articles/service-fabric/service-fabric-reliable-services-reliable-collections-transactions-locks.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Transactions And Lock Modes in Azure Service Fabric Reliable Collections | Microsoft Docs
3+
description: Azure Service Fabric Reliable State Manager and Reliable Collections Transactions and Locking.
4+
services: service-fabric
5+
documentationcenter: .net
6+
author: mcoskun
7+
manager: timlt
8+
editor: masnider,rajak
9+
10+
ms.assetid: 62857523-604b-434e-bd1c-2141ea4b00d1
11+
ms.service: service-fabric
12+
ms.devlang: dotnet
13+
ms.topic: article
14+
ms.tgt_pltfrm: na
15+
ms.workload: required
16+
ms.date: 5/1/2017
17+
ms.author: mcoskun
18+
19+
---
20+
# Transactions and lock modes in Azure Service Fabric Reliable Collections
21+
22+
## Transaction
23+
A transaction is a sequence of operations performed as a single logical unit of work.
24+
A transaction must exhibit the following ACID properties. (see: https://technet.microsoft.com/en-us/library/ms190612)
25+
* **Atomicity**: A transaction must be an atomic unit of work. In other words, either all its data modifications are performed, or none of them is performed.
26+
* **Consistency**: When completed, a transaction must leave all data in a consistent state. All internal data structures must be correct at the end of the transaction.
27+
* **Isolation**: Modifications made by concurrent transactions must be isolated from the modifications made by any other concurrent transactions. The isolation level used for an operation within an ITransaction is determined by the IReliableState performing the operation.
28+
* **Durability**: After a transaction has completed, its effects are permanently in place in the system. The modifications persist even in the event of a system failure.
29+
30+
### Isolation levels
31+
Isolation level defines the degree to which the transaction must be isolated from modifications made by other transactions.
32+
There are two isolation levels that are supported in Reliable Collections:
33+
34+
* **Repeatable Read**: Specifies that statements cannot read data that has been modified but not yet committed by other transactions and that no other transactions can modify data that has been read by the current transaction until the current transaction finishes. For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).
35+
* **Snapshot**: Specifies that data read by any statement in a transaction is the transactionally consistent version of the data that existed at the start of the transaction.
36+
The transaction can recognize only data modifications that were committed before the start of the transaction.
37+
Data modifications made by other transactions after the start of the current transaction are not visible to statements executing in the current transaction.
38+
The effect is as if the statements in a transaction get a snapshot of the committed data as it existed at the start of the transaction.
39+
Snapshots are consistent across Reliable Collections.
40+
For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).
41+
42+
Reliable Collections automatically choose the isolation level to use for a given read operation depending on the operation and the role of the replica at the time of transaction's creation.
43+
Following is the table that depicts isolation level defaults for Reliable Dictionary and Queue operations.
44+
45+
| Operation \ Role | Primary | Secondary |
46+
| --- |:--- |:--- |
47+
| Single Entity Read |Repeatable Read |Snapshot |
48+
| Enumeration, Count |Snapshot |Snapshot |
49+
50+
> [!NOTE]
51+
> Common examples for Single Entity Operations are `IReliableDictionary.TryGetValueAsync`, `IReliableQueue.TryPeekAsync`.
52+
>
53+
54+
Both the Reliable Dictionary and the Reliable Queue support Read Your Writes.
55+
In other words, any write within a transaction will be visible to a following read
56+
that belongs to the same transaction.
57+
58+
## Locks
59+
In Reliable Collections, all transactions implement rigorous two phase locking: a transaction does not release
60+
the locks it has acquired until the transaction terminates with either an abort or a commit.
61+
62+
Reliable Dictionary uses row level locking for all single entity operations.
63+
Reliable Queue trades off concurrency for strict transactional FIFO property.
64+
Reliable Queue uses operation level locks allowing one transaction with `TryPeekAsync` and/or `TryDequeueAsync` and one transaction with `EnqueueAsync` at a time.
65+
Note that to preserve FIFO, if a `TryPeekAsync` or `TryDequeueAsync` ever observes that the Reliable Queue is empty, they will also lock `EnqueueAsync`.
66+
67+
Write operations always take Exclusive locks.
68+
For read operations, the locking depends on a couple of factors.
69+
Any read operation done using Snapshot isolation is lock free.
70+
Any Repeatable Read operation by default takes Shared locks.
71+
However, for any read operation that supports Repeatable Read, the user can ask for an Update lock instead of the Shared lock.
72+
An Update lock is an asymmetric lock used to prevent a common form of deadlock that occurs when multiple transactions lock resources for potential updates at a later time.
73+
74+
The lock compatibility matrix can be found in the following table:
75+
76+
| Request \ Granted | None | Shared | Update | Exclusive |
77+
| --- |:--- |:--- |:--- |:--- |
78+
| Shared |No conflict |No conflict |Conflict |Conflict |
79+
| Update |No conflict |No conflict |Conflict |Conflict |
80+
| Exclusive |No conflict |Conflict |Conflict |Conflict |
81+
82+
Time-out argument in the Reliable Collections APIs is used for deadlock detection.
83+
For example, two transactions (T1 and T2) are trying to read and update K1.
84+
It is possible for them to deadlock, because they both end up having the Shared lock.
85+
In this case, one or both of the operations will time out.
86+
87+
This deadlock scenario is a great example of how an Update lock can prevent deadlocks.
88+
89+
## Next steps
90+
* [Working with Reliable Collections](service-fabric-work-with-reliable-collections.md)
91+
* [Reliable Services notifications](service-fabric-reliable-services-notifications.md)
92+
* [Reliable Services backup and restore (disaster recovery)](service-fabric-reliable-services-backup-restore.md)
93+
* [Reliable State Manager configuration](service-fabric-reliable-services-configuration.md)
94+
* [Developer reference for Reliable Collections](https://msdn.microsoft.com/library/azure/microsoft.servicefabric.data.collections.aspx)
95+

0 commit comments

Comments
 (0)