% $Id$
%
% Earth System Modeling Framework
% Copyright (c) 2002-2023, University Corporation for Atmospheric Research, 
% Massachusetts Institute of Technology, Geophysical Fluid Dynamics 
% Laboratory, University of Michigan, National Centers for Environmental 
% Prediction, Los Alamos National Laboratory, Argonne National Laboratory, 
% NASA Goddard Space Flight Center.
% Licensed under the University of Illinois-NCSA License.
%\subsection{Implementation Notes}
\begin{enumerate}

\item The Log class was implemented in Fortran and uses the Fortran I/O 
libraries when the class methods are called from Fortran. The C/C++ Log
methods use the Fortran I/O library by calling utility functions that are
written in Fortran. These utility functions call the standard Fortran write, 
open and close functions.  At initialization an {\tt ESMF\_LOG} is created. 
The {\tt ESMF\_LOG} stores information for a specific Log file.   When working 
with more than one Log file, multiple {\tt ESMF\_LOG}'s are required (one 
{\tt ESMF\_LOG} for each Log file).  For each Log, a handle is returned 
through the {\tt ESMF\_LogInitialize} method for the default log or {\tt ESMF\_LogOpen} for a user created log.  The user can specify single or multi logs by 
setting the {\tt logkindflag} property in the {\tt ESMF\_LogInitialize} or 
{\tt ESMF\_Open} method to {\tt ESMF\_LOGKIND\_SINGLE} or {\tt ESMF\_LOGKIND\_MULTI}.
Similarly, the user can set the {\tt logkindflag} property for the default
Log with the {\tt ESMF\_Initialize} method call.
The {\tt logkindflag} is useful as the PET numbers are automatically added to the 
log entries.  A single log will put all entries, regardless of PET number, 
into a single log while a multi log will create multiple logs with the PET 
number prepended to the filename and all entries will be written to their 
corresponding log by their PET number.

The properties for a Log are set with the {\tt ESMF\_LogSet()} method and 
retrieved with the {\tt ESMF\_LogGet()} method.

Additionally, buffering is enabled.  Buffering allows {\tt ESMF} to manage 
output data streams in a desired way.  Writing to the buffer is transparent 
to the user because all the Log entries are handled automatically by the 
{\tt ESMF\_LogWrite()} method.  All the user has to do is specify the buffer
size (the default is ten) by setting the {\tt maxElements} property.  Every 
time the {\tt ESMF\_LogWrite()} method is called, a LogEntry element is 
populated with the {\tt ESMF\_LogWrite()} information.  When the buffer is 
full (i.e., when all the LogEntry elements are populated), the buffer will be 
flushed and all the contents will be written to file.  If buffering is not 
needed, that is {\tt maxElements=1} or {\tt flushImmediately=ESMF\_TRUE}, 
the {\tt ESMF\_LogWrite()} method will immediately write to the Log file(s).
\end{enumerate}
