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:
-
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 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:
- Checking for processing timeout limit
- 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.
