====== Loggers ======

If you need to regularly check what kind of data is flowing over a certain channel, you can use loggers to more elegantly watch the activity. A logger will only report tokens of data values successfully transmitted over the channel and thus hopefully help unclog your log and ease your debugging experience. We offer two different loggers, one logging to console and one logging to a file.

Loggers are not sinks! They can be put between two components without influencing their slack (zero-slack behavior, see [[https://link.springer.com/content/pdf/10.1007/BFb0054295.pdf | Slack Elasticity in Concurrent Computing, R. Manohar and A.J. Martin]] for more information on slack). If you need a token sink, either look at [[sim:sinks | standard sinks]] for prototyping or [[sim:scoreboards | scoreboards]] for a testing harness.

===== Parameters =====

   * ''D_WIDTH'': The bit width of the data bus
   * ''IN_CHANNELS'': The number of channels passing through the logger
   * ''LOG_ID'': ID of the logger to be used in log output
   * ''LOG'': Toggles whether or not the logger should post a log line whenever a token is encountered

Additionally, the file logger has two more parameters:

   * ''VERBOSITY'': The level of verbosity with which data should be written to the outfile, where 0 is the least verbose, and 2 is maximum verbosity
   * ''F_ID'': The ID of the file to write to

Only one logger can write to a given file at the same time, read and write access to a file is not possible.

Files in actsim use a common simulation file prefix. By default, this is ''_outfile_.'', where the period is followed by a number, from hereon out referred to as a *file ID*. You can alias a given file ID with a different file name that does not adhere to this naming scheme using an actsim config file. The following is a copy of the default actsim configuration.

<code>
#
# parameters for external file names for sim::file* functions
#
begin file
    # by default, file names will be prefix.<number>
    string prefix "_infile_"

    # alternatively, you can specify file names here
    # where 0 = first file name, 1 = second file name, etc.
    # string_table name_table "file1.in" "file2.in"

    # by default, output file names will be prefix.<number>
    string outprefix "_outfile_"
    # alternatively, you can specify output file names here
    # where 0 = first file name, 1 = second file name, etc.
    # string_table outname_table "file1.in" "file2.in"
end
</code>

This configuration can be found on your local machine by going to ''$ACT_HOME/conf/generic/actsim.conf''.
Please see [[tools:actsim | the actsim documentation page]] for more details.

===== Interface =====

   * ''I'': Token input channels, array of size ''IN_CHANNELS''
   * ''O'': Token output channels, array of size ''IN_CHANNELS''

The available processes are:

<code act>
export template<pint D_WIDTH, IN_CHANNELS, LOG_ID; pbool LOG>
defproc logger (chan?(int<D_WIDTH>) I[IN_CHANNELS]; chan!(int<D_WIDTH>) O[IN_CHANNELS]);

export template<pint D_WIDTH, IN_CHANNELS, VERBOSITY, F_ID, LOG_ID; pbool LOG>
defproc logger_file (chan?(int<D_WIDTH>) I[IN_CHANNELS]; chan!(int<D_WIDTH>) O[IN_CHANNELS]);
</code>