Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

C/C++ API Documentation | 2025.1

# ClientProgress - progress indicators for P4 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()`

Copy

    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

Progress Unit Type | Defined in clientprog.h | Value
--- | --- | ---
Unspecified | `CPU_UNSPECIFIED` | `0`
Percentage Complete | `CPU_PERCENT` | `1`
Number of files | `CPU_FILES` | `2`
KB (1024 bytes) | `CPU_KBYTES` | `3`
MB (1024*1024 bytes) | `CPU_MBYTES` | `4`
Number of deltas | `CPU_DELTAS` | `5`
Number of items | CPU_ITEMS | 6
Number of directories | CPU_DIRS | 7

Additional progress types or progress units might be added in future releases of P4 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:

Type | Defined in clientprog.h | Value | Introduced | Meaning
--- | --- | --- | --- | ---
`SendFile` | `CPT_SENDFILE` | `1` | 2012.2 | Files sent to the server. This represents the source path, that is, the local path to the file being sent. The progress unit type is KB (3) or Deltas (5), depending on transfer mechanism. See Notes in ClientProgress::Description( const StrPtr *, int ). The total for ClientProgress::Total( long ) is the total bytes or deltas to send.
`ReceiveFile` | `CPT_RECVFILE` | `2` | 2012.2 | Files received from server. This represents the destination path, that is, the local path to the file being received. The progress unit type is KB (3). The total for ClientProgress::Total( long ) is the total bytes to receive. This progress notification depends on the client receiving the filesize from the server, which is a feature that requires a 2020.2 or later P4 Server.
`Files` | `CPT_FILES` | `3` | 2012.2 | Miscellaneous file events. This replaces `CPT_FILESTRANS` (still defined for backwards compatibility) but uses the same type value (3) because not all file events involve transfers.
`Computation` | `CPT_COMPUTATION` | `4` | 2012.2 | Computation performed server-side.
Items | CPT_ITEMS | 5 | 2015.1 | Revisions, integrations, and other items that are not files.
Dirs | CPT_DIRS | 6 | 2015.1 | Directories transmitted.
DeleteFile | CPT_DELFILE | 7 | 2015.1 | Files deleted.

Additional progress types or progress units might be added in future releases of P4 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

Description | Type | Units | Total
--- | --- | --- | ---
The local path to the file being sent from the client. | SendFile(1) | KB(3) or Deltas(5) depending on transfer mechanism. | Total bytes or deltas to send.

#### Receive File

Description | Type | Units | Total
--- | --- | --- | ---
The local path to the file being received by the client. | ReceiveFile(2) | KB(3) | Total bytes or deltas to receive.

#### Delete File

Description | Type | Units | Total
--- | --- | --- | ---
The local path to the file being deleted. This progress notification is to indicate that a file delete happened. This might happen during a sync, and would be included in the total files to sync, so is useful for tracking sync progress. Introduced in the 2025.1 P4API, but backwards compatible with older servers. | DeleteFile(7) | Files(2) | Always 1

#### ReconcileAdd

Description | Type | Units | Total
--- | --- | --- | ---
Reconcile Add. This progress notification increments as each directory of files is scanned for new files. Introduced in the 2025.1 P4API, and requires a 2025.1 or higher server. | Dirs(6) | Dirs(7) | Unspecified(0)

#### ReconcileEdit

Description | Type | Units | Total
--- | --- | --- | ---
Reconcile Edit. This progress notification increments for each file being checked for modification or delete. Updates are rate limited at 500ms. Introduced in the 2025.1 P4API, and requires a 2025.1 or higher server. | Files(3) | Files(2) | Number of files to check.

#### ReconcileMatchDigest

Description | Type | Units | Total
--- | --- | --- | ---
Matching digest. This progress notification increments for each file matched. Updates are rate limited at 500ms. Introduced in the 2025.1 P4API, and requires a 2025.1 or higher server. | Files(3) | Files(2) | Number of deleted files to attempt to match to an add by exact digest.

#### ReconcileMatchContent

Description | Type | Units | Total
--- | --- | --- | ---
Matching content. This progress notification increments for each file diffed. Updates are rate limited at 500ms. Introduced in the 2025.1 P4API, and requires a 2025.1 or higher server. | Files(3) | Files(2) | Number of deleted files to diff against added files

### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`command paused` | Computation(4) | Unspecified(0) | Number of times the connection has been considered for resumption.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`sync` | FilesTransfering(3) | Files(2) Prior to 2025.1, was Unspecified(0). | Number of files to be transferred.

#### DVCS - Check revisions

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.

Description | Type | Units | Total
--- | --- | --- | ---
`check revisions` Prior to 2025.1, was check files | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`check integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`commit revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`commit integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Integration record count.

#### DVCS - Fetch load revisions

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

Description | Type | Units | Total
--- | --- | --- | ---
`fetch load revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### DVCS - Fetch load integrations

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

Description | Type | Units | Total
--- | --- | --- | ---
`fetch load integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### DVCS - Push load revisions

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

Description | Type | Units | Total
--- | --- | --- | ---
`push load revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### DVCS - Push load integrations

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

Description | Type | Units | Total
--- | --- | --- | ---
`push load integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`fetch archives` | FilesTransfering(3) | Files(2) Prior to 2025.1, was Unspecified(0) | The number of archives 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.

Description | Type | Units | Total
--- | --- | --- | ---
`push archive` | FilesTransfering(3) | Files(2) Prior to 2025.1, was Unspecified(0) | The number of archives 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.

Description | Type | Units | Total
--- | --- | --- | ---
`unzip check revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`unzip check integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Integration record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`unzip commit revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### 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.

Description | Type | Units | Total
--- | --- | --- | ---
`unzip commit integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### Unzip - Unzip archives

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

Description | Type | Units | Total
--- | --- | --- | ---
`unzip archives` | FilesTransfering(3) | Files(2) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### Zip - Zip revisions

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

Description | Type | Units | Total
--- | --- | --- | ---
`zip revisions` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Revision record count.

#### Zip - Zip integrations

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

Description | Type | Units | Total
--- | --- | --- | ---
`zip integrations` | Items(5) Prior to 2025.1, was FilesTransfering(3) | Items(6) Prior to 2025.1, was Unspecified(0) | Not applicable.

#### Zip - Zip archives

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

Description | Type | Units | Total
--- | --- | --- | ---
`zip archives` | FilesTransfering(3) | Files(2) Prior to 2025.1, was Unspecified(0) | Not applicable.

Your search for returned results