When FreeMarker generates the output, it's usually not sent immediately to the final receiving party (like a web browser or a destination file), but is accumulated in a buffer, then it's sent out in bigger chunks. The exact rules of the buffering is not decided by FreeMarker, but by the embedding software. Sending out the content accumulated in the buffer is called flushing. Although flushing happens automatically, sometimes you want to force it on certain points of the template processing, and this is what the
flush directive does. Whether it's needed at certain points should be decided by a programmer, not a designer.
Note that while
flush tells the embedding software that we want to flush, that might as well decides to ignore this request. It's not in the hands of FreeMarker.
Flush simply calls the
flush() method of the currently used
java.io.Writer instance. The whole buffering and flushing mechanism is implemented in the
Writer (that you have passed as the parameter of the
Template.process method); FreeMarker does not deal with it.