Alerting Library Users to an Inconsistent State

Question

In a managed wrapper over a native library, I have to accomplish certain operations which to the user of the high level objects should be considered atomic and consistent. However, the underlying operations in native code are atomic and consistent individually, but not as a whole.

// Simplistic look at the AddRange operation
void AddRange(IEnumerable<ChildType> range)
{
    foreach (var value in range)
    {
        this.NativeAdd(value);
    }
}

// Simplistic look at the Delete operation
void Delete(ParentType value)
{
    foreach (var child in value.Children)
    {
        this.NativeDelete(child);
    }

    this.NativeDelete(value);
}

All of the Native operations fail with a common exception type if the Native code relates there has been an error:

void NativeDelete(ChildType child)
{
    StatusCode status = StatusCode.NoError;
    NativeMethods.DeleteChild(this.id, child.Id, out status);

    if (status != StatusCode.NoError)
    {
        throw new LibraryException(this, child, status);
    }
}

In the high-level AddRange and Delete routines I run into the situation where some of either the native Add or Delete calls have completed, but an error occurs in one of them and the rest do not complete.

UPDATE: The actual file on disk, to a user, will not look any different if they added 7 items and it failed on the 7th item, or if they added 6 items successfully. The only time the error is recorded is during runtime. Therefore, if the user is not made aware of the possibility of an inconsistent state, they may not be able to decide if the underlying file is valid.

Should I:

1. Let the LibraryException through and provide documentation to the user that the ParentType or ChildType object may be in an inconsistent state
2. Wrap the LibraryException in an InconsistentStateException containing information about which objects may be in an inconsistent state
3. Catch the LibraryException and attempt to "hand" rollback the changes made, before rethrowing the exception for the user (not a fan of this)
4. Something else?

Answer 1

I like your second option -

This would provide a much more meaningful exception, which you'd control. There's no reason to force your end users to understand some strange status codes, etc. At least this way, it'll be obvious what happened and why.

Answer 2

3 just isn't possible without a true two-phase commit support (i.e. a transaction manager). Rolling back by hand is just going to lead you to more of an inconsistent state if an error occurs there.

I think 2 is redundant. If you call a method on the parent type (which is where these methods exposed) and you have an exception that occurs when you throw that exception, the assumption is that the state on the object is corrupted (with the exception of a few exceptions). Generally, when that occurs, you can't do much with the object except throw it away and use a new one with a consistent state.

That leaves 1, to document it. While you might give a lot of structured information in 2, if the object is in an inconsistent state, you really don't want to try and fix that state, as you run a greater risk of screwing it up more.

Answer 3

If I understand your update correctly, all the caller can do is pass the information on to the end user, who has to decide whether to accept the state, or to roll back.

In that case, (2): provide all information so the caller can pass the information to the user, or a log file, or some statistics without a lot of work.

(1) would be ok if there is no informational difference to (2), e.g. knowing which item failed is irrelevant.

(3) is pointless if you can't expect fix it most of the time, and dangerous if there is the slightest chance you make it worse.

Depending on the file size you might be able to make the change quasi-atomic by working on a copy. At least, the user would probably expect an easy way to roll back to the last save.