Thread aware

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:

  1. Analyzing template

    Opening template
  2. Processing data

    Processing data
  3. Flushing output

    Zipping files

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 14+ 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 stopping/interrupting the thread which does the processing.
For this purpose Templater has various check for current thread status and will throw ThreadInterruptedException in .NET or InterruptedException in JVM if it detects request for thread interrupt.
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:

  1. Checking for processing timeout limit
  2. Checking for system available memory

In case of either of those problems thread.interrupt() should be called and Templater will stop with processing on the next check for thread interrupt.

Back to Features