PendingActionCount Property (TarArchive)

Gets a value indicating the number of pending actions on the archive.

Syntax

Visual Basic
C#

'Declaration
 
Public ReadOnly Property PendingActionCount As Long

'Usage
 
Dim instance As TarArchive
Dim value As Long
 
value = instance.PendingActionCount

public long PendingActionCount {get;}

Property Value

A value indicating the number of pending actions on the archive.

Remarks

A pending action typically refers to a batch update started by a call to TarArchive.BeginUpdate. It can also refer to open streams on one of the archive's items.

The count is incremented when an action is started and decremented when that action is completed. So methods like TarArchive.BeginUpdate, TarredFile.OpenRead, and TarredFile.OpenWrite increment the count. Methods like TarArchive.EndUpdate and Stream.Close decrement the count.

When the count is at zero, it means all batched updates on the archive have been written and the archive is rebuilt and is now in an unmodified state.

In most cases, for optimization reasons, the archive is only rebuilt when the pending action count reaches zero, typically when TarArchive.EndUpdate is called.

This property is meant as a debugging aid to make sure no actions are incomplete when an application has finished modifying an archive. For example, a call to TarArchive.EndUpdate might be expected to rebuild the archive. But if a Stream from a TarredFile is left open during the update, TarArchive.EndUpdate will do nothing since the pending action count won't reach zero with the call.

If this property returns a value greater than zero after a call to the last nested TarArchive.EndUpdate, it usually means there is a logic error in the application and not all resources have been returned to the archive. This will lead to corrupted archives.

Example

VB.NET
C#

Dim tarFile As AbstractFile = New DiskFile("PendingActionCountExample.tar")
If tarFile.Exists Then
  tarFile.Delete()
End If

Dim tar As New TarArchive(tarFile)

tar.BeginUpdate()

Dim file As AbstractFile = tar.GetFile("SomeFile.dat")
Dim stream As Stream = file.CreateWrite()

' EndUpdate() will do nothing since 'stream' is still open
tar.EndUpdate()

' Assert() will fail here because of the logic error
System.Diagnostics.Debug.Assert(tar.PendingActionCount <= 0)

AbstractFile tarFile = new DiskFile( "PendingActionCountExample.tar" );
if( tarFile.Exists )
  tarFile.Delete();

TarArchive tar = new TarArchive( tarFile );

tar.BeginUpdate();

AbstractFile file = tar.GetFile( "SomeFile.dat" );
Stream stream = file.CreateWrite();

// EndUpdate() will do nothing since 'stream' is still open
tar.EndUpdate();

// Assert() will fail here because of the logic error
System.Diagnostics.Debug.Assert( tar.PendingActionCount <= 0 );

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

TarArchive Class
TarArchive Members