Execution monitoring
Templater methods are CPU bound.
Most of the time Templater will load all relevant data in memory upfront and then perform various calculations to create the final document while operating on the document representation in memory.
Regardless of streaming support in some use cases, it will block while processing the document.
Templater processing could be visualized with three steps as:
-
Analyzing template
-
Processing data
-
Flushing output
First step is almost never a problem. It's performed on smallish input files, does not take long and allocates non-significant amount of memory.
Second steps involves calls to Resize and Replace methods in Templater.
While Replace usually does not take significant amount of memory when called huge number of times it will accumulate CPU time over duration of processing.
Calling Resize with large count size can allocate significant amount of memory and will perform analysis which can take significant amount of CPU time.
Third step involves flushing of in memory structures into XML inside Office zip formats. This step can take significant amount of memory. For processing on Java we recommend using Java 11+ since it includes patch to significantly improve memory usage while flushing XML.
Pattern for safer processing in web/desktop applications
Java and .NET lack process forking ability so the only viable workaround against excessive CPU/memory usage is cancelling the Templater processing.
For this purpose Templater has cancellation token argument and will stop processing soon after it signals cancellation. Relevant exceptions will be thrown in those cases:
OperationCanceledException in .NET or
CancellationException in JVM.
Its common to set up processing on a separate thread, or just pass in relevant cancellation token which will abort the execution on the current thread.
If processing setup is done by starting a new thread which does the actual processing,
guards can be added in the start location to minimize the problems which can arise from unexpected processing:
- Checking for processing timeout limit
- Checking for system available memory
In case of either of those problems CancellationTokenSource should mark token as canceled or in Java CancellationToken implementation should start returning true. Templater will stop with processing on the next check for the provided token.
