ClientProgress - progress indicators for Helix Core Server commands

The ClientProgress class introduced in 2012.2 provides a means to report on the progress of running commands. You can customize this behavior by subclassing ClientUser and ClientProgress.

The methods of your ClientProgress object will be called during the life of a server command. Usually, Description() is called first with a description and a units from the server. The units of measure apply to the Total() and Update() methods.

Total() is called if a there is a known upper bound to the number of units. Update() is called from time to time as progress is made. If your Update() implementation returns non-zero, the API assumes the user has also attempted to cancel the operation.

Done() is called last, with the fail argument being non-zero in case of failure. When the command is complete, the API destroys the object by calling the destructor.

Default implementations are used in the p4 command-line client, and report on the progress of p4 -I submit and p4 -I sync -q.

Handling progress notifications

The ClientProgress class contains a collection of progress notification callback methods. If you want your application to handle progress notifications, subclass the ClientProgress class and in ClientUser, implement ClientUser::CreateProgress() and ClientUser::ProgressIndicator(). Notifications of parallel sync, submit, shelve, and unshelve are supported through ClientUser::CanParallelProgress().

In ClientProgress, implement ClientProgress::Description(), ClientProgress::Total(), ClientProgress::Update(), and ClientProgress::Done()

class ClientProgress {
public:
    virtual ~ClientProgress() {};
    virtual void    Description( const StrPtr *desc, int units ) = 0;
    virtual void    Total( long ) = 0;
    virtual int    Update( long ) = 0;
    virtual void    Done( int fail ) = 0;
};

The two forms of the CreateProgress method are ClientUser::CreateProgress( int ) or ClientUser::CreateProgress( int, P4INT64 ). The CreateProgress method will have had the progress type (see Progress types), which it could pass into the ClientProgress subclass's constructor. Alternatively, the CreateProgress method might have used the progress type to choose the subclass of ClientProgress.

ClientProgress::~ClientProgress()

Once returned from ClientUser::CreateProgress the ClientUser object will be owned by the client and will be deleted after the call to ClientProgress::Done( int ), where the integer is 1 to indicate failure: ClientProgress::Done( int fail ). Deleting the client-owned ClientProgress object will result in access to initialized memory.

ClientProgress::Description( const StrPtr *desc, int units ) will be called with a textual description of the progress. If this is a file transfer, this will typically be a depot file path. The units parameter exposes which unit of work will be received by ClientProgress::Total( long ) and ClientProgress::Update( long ).

ClientProgress::Total( long ) will be called with the total number of units this ClientProgress should expect. This is typical for cases where there is a known target value, which can be presented as a progress bar.

ClientProgress::Update( long ) will be called each time there is an update to the progress. If ClientProgress::Total( long ) was not called, ClientProgress::Update( long ) should be used to show to show that work is still happening, such as a spinner.

ClientProgress::Done( int fail ) will be called once the context for the progress has completed. If fail is set to non-zero, there was an error and the operation was unsuccessful.

Progress Units

Additional progress types or progress units might be added in future releases of Helix Core Server. These types and units can be passed into CreateProgress() regardless of the P4API version. Your implementation can either handle unknown types and units generically or ignore them.

Progress types

The API calls this method with the appropriate ProgressType as defined in clientprog.h. The following ProgressTypes can be reported:

Additional progress types or progress units might be added in future releases of Helix Core Server. These types and units can be passed into CreateProgress() regardless of the P4API version. Your implementation can either handle unknown types and units generically or ignore them.

Progress sources

Client side

Send File

Receive File

Server side

Resource Pressure Pause

Notification is sent if the resource pressure system has paused the connection. The update value will reflect how many times the connection has been considered for resumption. Re-evaluation occurs every 100 to 200 milliseconds. Update notifications are rate limited to 1 every 500 milliseconds.

Sync

An indication of the number of files transferred versus the total files to be transferred for a non-parallel p4 sync with the -q option.

To give both files-in-sync progress and per-file progress:

1. Run the sync in tagged mode. The first result contains the total files and bytes to be transferred.

2. Count the per-file progress instances.

The first call to clientStat includes the total file count and an estimate of the total bytes to transfer. After that, each call to ClientUser::CreateProgress( int, P4INT64 ) signifies a file being received. The progress of the file can be displayed. When the ClientProgress::Done() callback is called, the number of files transferred can be incremented to show the progress per file of the sync. This also works for parallel sync if ClientUser::CanParallelProgress() is made to return 1.

DVCS - Check files

An indication of how many file revisions have been checked as part of a DVCS push/fetch and how many more need to be processed.

DVCS - Check integrations

An indication of how many file revisions have been checked as part of a DVCS push/fetch and how many more need to be processed.

DVCS - Commit revisions

An indication of how many file revisions have been written to the database as part of a DVCS push/fetch and how many more need to be written.

DVCS - Commit integrations

An indication of how many file integratio ns have been written to the database as part of a DVCS push/fetch and how many more need to be written.

DVCS - Fetch load revisions

An indication of how many file revisions have been read from the database as part of a DVCS fetch.

DVCS - Fetch load integrations

An indication of how many file integrations have been read from the database as part of a DVCS fetch.

DVCS - Push load revisions

An indication of how many file revisions have been read from the database as part of a DVCS push.

DVCS - Push load integrations

An indication of how many file integrations have been read from the database as part of a DVCS fetch.

DVCS - Fetch archives

An indication of how many archives have been transferred as part of a DVCS fetch and how many are left to transfer.

DVCS - Push archives

An indication of how many archives have been transferred as part of a DVCS fetch and how many are left to transfer.

Unzip - Check revisions

An indication of how many file revisions have been checked as part of a p4 unzip operation and how many more need to be processed.

Unzip - Check integrations

An indication of how many file integrations have been checked as part of a p4 unzip operation and how many more need to be processed.

Unzip - Commit revisions

An indication of how many file revisions have been written to the database as part of a p4 unzip operation and how many more need to be written.

Unzip - Commit integrations

An indication of how many file integrations have been written to the database as part of a p4 unzip operation and how many more need to be written.

Unzip - Unzip archives

An indication of how many archives have been unzipped as part of a p4 unzip operation.

Zip - Zip revisions

An indication of how many file revisions have been read from the database as part of a p4 zip operation.

Zip - Zip integrations

An indication of how many file integrations have been read from the database as part of a p4 zip operation.

Zip - Zip archives

An indication of how many archives have been added to the zip as part of a p4 zip operation.