Progress Monitoring

Introduction

Some Mako operations, particularly those operating on large documents, can take a long time. In an interactive application, evidence of progress by means of UI element such as a progress bar or even just a “spinner” of some kind reassures the user that something is happening and that the application has not hung.

Mako provides these classes to enable implementation of such mechanisms:

Class	Description
`IProgressMonitor`	An abstract class encapsulating both an `IProgressTick` and an `IAbort` so that the caller can monitor the progress and/or abort the processing.
`IProgressTick`	An abstract class allowing a callback to monitor the progress of a task. The callback can either pass an integer (from 0 to a maximum value) or a float (0.0 to 1.0) which represents the progress of the task.
`IAbort`	A simple class to signal an abort in processing.

In principle, adding progress monitoring involves these steps:

Create a progress tick call back function
Create an IProgressTick referencing the call back function
Creating an IProgressMonitor with the IProgressTickinstance and an IAbortinstance
Attach the progress monitor to the process to be monitored by passing in the IProgressMonitor instance

Thereafter, the call back function will be called on a regular ‘tick’, the number of which is determined by the work being done. The interval of the ticks can be controlled, and a maximum number can be specified, so that as the process continues, the tick will incrementally approach the maximum. The tick call back can be an integer or a float.

The call back can also interrupt the process by signalling an abort. This is shown in the accompanying page that looks in more detail at monitoring transforms.

Sample Code

To help you understand how to implement progress monitoring in your development, we have created sample code, attached, that does the following:

✅Demonstrates the Use of `IProgressMonitor`, `IProgressTick`, and `IAbort`

The code initializes and uses progress-related objects, showing how to:
- Create progress monitors (IProgressMonitor::create).
- Attach them to different stages of processing (custom transformation, general transformation, transform chain).
- Use IProgressTick to trigger progress updates.

✅ Multiple Progress Monitors for Different Stages

The sample shows progress tracking at multiple levels:
- Custom Transform (m_customTransformProgressMonitor)
- Single Transform (m_transformProgressMonitor)
- Transform Chain (m_transformChainProgressMonitor)
These show how to instrument various stages of their processing pipeline.

✅ Encapsulation of Progress Handling (`ProgressHandler` Class)

ProgressHandler::create() simplifies instantiation.
The tick() method demonstrates periodic updates.
The callbackInt() method links progress updates back to the ProgressHandler.

Code Examples

Examples are provided in C++ & C#. For the full implementations see ProgressMonitoring.cpp or ProgressMonitoringCS.cs. Below are some relevant snippets.

ProgressHandler class

C++

C#

CPP

class ProgressHandler
{
    // This section should be customised
public:

    explicit ProgressHandler(std::string info = "") : m_info(std::move(info)), m_tickCount(0) {}

    void tick(uint32_t currentCount, uint32_t maxCount)
    {
        m_tickCount++;

        printf("%s : %d\n", m_info.c_str(), m_tickCount);
        fflush(stdout); 
    }

    // Everything below this part can be reused
    IProgressTickPtr    m_progressTick;

    static std::shared_ptr<ProgressHandler>  create(const std::string& info)
    {
        std::shared_ptr<ProgressHandler> progressHandler = std::make_shared<ProgressHandler>(info);

        progressHandler->m_progressTick = IProgressTick::create(callbackInt, progressHandler.get());

        return progressHandler;
    }

protected:

    static void callbackInt(void* priv, uint32_t currentCount, uint32_t maxCount)
    {
        ProgressHandler* progressHandler = (ProgressHandler*)priv;

        progressHandler->tick(currentCount, maxCount);
    }

private:

    std::string     m_info;
    int             m_tickCount;
};

C#

class ProgressTick : IProgressTickIntCallback
{
    public int m_tickCount;
    public string m_info;

    public ProgressTick(string info)
    {
        m_info = info;
        m_tickCount = 0;
    }

    public override void tick(uint tickNo, uint maxTick)
    {
        m_tickCount++;
        Console.Out.WriteLine($"{m_info} {m_tickCount}");
    }
};

class ProgressTickHandler
{
    public IProgressTick? m_progressTick;
    private IProgressTickIntCallback? m_callback;

    ProgressTickHandler()
    {
        m_progressTick = null;
        m_callback = null;
    }

    public static ProgressTickHandler create(IProgressTickIntCallback callback)
    {
        var handler = new ProgressTickHandler();

        handler.m_callback = callback;
        handler.m_progressTick = IProgressTick.create(callback.getCallbackFunc(), callback.getPriv());

        return handler;
    }
};

Create Progress Monitors

C++

C#

CPP

// ----- Create ProgressHandlers -----
std::shared_ptr<ProgressHandler> customTransformProgressHandler = ProgressHandler::create("customtransform");
std::shared_ptr<ProgressHandler> transformProgressHandler = ProgressHandler::create("transform");
std::shared_ptr<ProgressHandler> transformChainProgressHandler = ProgressHandler::create("transformChain");

// ----- Create ProgressMonitors -----
IAbortPtr abort = IAbort::create();

cvtParams.m_customTransformProgressMonitor = IProgressMonitor::create(customTransformProgressHandler->m_progressTick, abort);
cvtParams.m_transformProgressMonitor = IProgressMonitor::create(transformProgressHandler->m_progressTick, abort);
cvtParams.m_transformChainProgressMonitor = IProgressMonitor::create(transformChainProgressHandler->m_progressTick, abort);

C#

// ----- Create ProgressHandlers -----
var customTransformProgressHandler = ProgressTickHandler.create(new ProgressTick("customtransform"));
var transformProgressHandler = ProgressTickHandler.create(new ProgressTick("transform"));
var transformChainProgressHandler = ProgressTickHandler.create(new ProgressTick("transformChain"));

// ----- Create ProgressMonitors -----
var abort = IAbort.create();

cvtParams.m_customTransformProgressMonitor = IProgressMonitor.create(customTransformProgressHandler.m_progressTick, abort);
cvtParams.m_transformProgressMonitor = IProgressMonitor.create(transformProgressHandler.m_progressTick, abort);
cvtParams.m_transformChainProgressMonitor = IProgressMonitor.create(transformChainProgressHandler.m_progressTick, abort);

Add progress monitors to transforms

C++

C#

CPP

// Create the transform
CEmptyTransformImplementation implementation(jawsMako);
ITransformPtr customTransform = ICustomTransform::create(jawsMako, &implementation);
customTransform->setProgressMonitor(cvtParams.m_customTransformProgressMonitor);

IColorConverterTransformPtr ccTransform = IColorConverterTransform::create(jawsMako);
IDOMColorSpacePtr deviceCmyk = IDOMColorSpaceDeviceCMYK::create(jawsMako);
ccTransform->setTargetSpace(deviceCmyk);
ccTransform->setProgressMonitor(cvtParams.m_transformProgressMonitor);


ITransformChainPtr transformChain;
{
    IColorConverterTransformPtr colorConverter = IColorConverterTransform::create(jawsMako);

    transformChain = ITransformChain::create(jawsMako, cvtParams.m_transformChainProgressMonitor);

    transformChain->pushTransform(colorConverter);
}

C#

// Create the transform
var implementation = new CEmptyTransformImplementation(jawsMako);
ITransform customTransform = ICustomTransform.create(jawsMako, implementation);
customTransform.setProgressMonitor(cvtParams.m_customTransformProgressMonitor);

var ccTransform = IColorConverterTransform.create(jawsMako);
IDOMColorSpace deviceCmyk = IDOMColorSpaceDeviceCMYK.create(jawsMako);
ccTransform.setTargetSpace(deviceCmyk);
ccTransform.setProgressMonitor(cvtParams.m_transformProgressMonitor);


ITransformChain transformChain;
{
    var colorConverter = IColorConverterTransform.create(jawsMako);

    transformChain = ITransformChain.create(jawsMako, cvtParams.m_transformChainProgressMonitor);

    transformChain.pushTransform(colorConverter);
}

Introduction

Sample Code

✅Demonstrates the Use of IProgressMonitor, IProgressTick, and IAbort

✅ Multiple Progress Monitors for Different Stages

✅ Encapsulation of Progress Handling (ProgressHandler Class)

Code Examples

ProgressHandler class

Create Progress Monitors

Add progress monitors to transforms

✅Demonstrates the Use of `IProgressMonitor`, `IProgressTick`, and `IAbort`

✅ Encapsulation of Progress Handling (`ProgressHandler` Class)