Smart Clients and System.Transactions Part 4 – The Transaction Sink

This is the fourth installment of an ongoing series about using System.Transactions as the fundament for client-side infrastructure for managing changes among loosely coupled components.

Previous posts: Introduction, Timeout, Enlistments

---

This series is supposed to be about something I called "change gathering infrastructure", but up until now there has been precious little change gathering going on. But now at last we're ready to take a closer look at this.

Here's the entire definition of the IAmbientTransaction interface. I've showed it before without the ReceiveChanges signature.

public interface IAmbientTransaction
{
    void Enlist(IEnlistmentNotification enlistmentNotification, EnlistmentOptions options);
    void ReceiveChanges(string changeKey, object changes);
}

This is the method that the providers use in order to give notice of the changes that they have collected during the current transaction. The natural method where the providers do this is in the Prepare() method, which constitutes the first part of the two phase commit implemented by System.Transactions. So, the Prepare() method of the transactional provider typically looks like this:

public void Prepare(PreparingEnlistment preparingEnlistment)
{
    ambientTransaction.ReceiveChanges(typeof(T).FullName, GetChanges());
    preparingEnlistment.Prepared();
}

The ambient transaction delegates the task of receiving changes to an object implementing IAmbientTransactionSink. The work is shared between them as follows: the transaction acts as the facade (the providers don't know anything about the sink) and in addition is responsible for knowing when every provider has sent their changes, while the sink knows how to transform all received changes and transform them into a message to be sent to the server for replay.

Here's the definition of the sink:

public interface IAmbientTransactionSink : IEnlistmentNotification
{
    void ReceiveChanges(string changeKey, object changes);
    void WriteAllChanges();
}

How does the ambient transaction know when all changes have been received?

Originally I thought I had found a simple and elegant solution to this problem, one that didn't even burden the transaction with the additional task of knowing when every change has been received. Notice the commit coordinated by System.Transactions is two-phase; first every enlistment receives the Prepare() method, and then the Commit() method. It is recommended that all enlistments do the brunt of their work in the Prepare() method, and this is where the transactional providers send in their changes. So, I thought, if I design the sink so that it does nothing during Prepare(), it can be sure that all providers have registered their changes when it receives the Commit() message: everybody does their work during Prepare() except the sink which does its work (assembling a change request and sending it to the server for replay ) during Commit().

However, this idea is flawed, and to understand why you have to know how and when the Rollback() message is invoked on the enlistments:

When and how may a System.Transactions Rollback carried through?

There are two possible ways that the Rollback() message is distributed to the enlisted providers:

1. Complete() never sent to the TransactionScope


    a. Because the logic in the program explicitly decides not to do so


    b. Because an exception causes program execution to jump directly to the implicit


2. Prepare() not sent to preparing enlistment in the Prepare() method of a provider


    a. Because the enlistment deliberately decides not to set the flag because it for some reason wants the transaction to be aborted.


    b. Because an exception in the Prepare code of the enlistment is raised.

Notice that all of these methods for instigating a rollback happen before the Commit() phase has been reached. This means that it is impossible to start a rollback after this phase has been reached. My original idea of having the sink do its work in the Commit method therefore is a no go: if something goes wrong here (and it inevitably will) I have no way of rolling back graciously.

So what have I learned here: don't do any work in the Commit() method of your enlistments. This method should only be used for doing risk free management of internal data structures (clearing lists, resetting counters and similar).

The solution

So the solution is pretty simple. Let the ambient transaction keep track of how many enlistments there are in total, and how many that have delivered their changes. When all enlistments are done, the transaction sink can be ordered to send the change message. Below are some of the code snippets involved in this process:

public void ReceiveChanges(string changeKey, object changes)
{
    enlistmentCount--;
    transactionSink.ReceiveChanges(changeKey, changes);

    if (enlistmentCount == 0)
        transactionSink.WriteAllChanges();
}
public void Commit(Enlistment enlistment)
{
    if (enlistmentCount > 0)
    {
        throw new TransactionException(String.Format("enlistmentCount = {0} in Commit()", enlistmentCount));
    }
    ExitTransaction();
    enlistment.Done();
}

public void Rollback(Enlistment enlistment)
{
    ExitTransaction();
    enlistment.Done();
}
 private void ExitTransaction()
{
    
    enlistments.Clear();
    enlistmentCount = 0;
}

Ok, this almost wraps it up for this series, however I still haven't explained how we solved the timout problem. This will be the topic of the next (an final) post in this series.