Merge pull request #245 from wclodius2/logger-safe-async-io

Logger safe async io

Author: milancurcic

doc/specs/index.md

@@ -15,6 +15,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
  - [error](./stdlib_error.html) - Catching and handling errors
  - [IO](./stdlib_io.html) - Input/output helper & convenience
  - [linalg](./stdlib_linalg.html) - Linear Algebra
+ - [logger](./stdlib_logger.html) - Runtime logging system
  - [optval](./stdlib_optval.html) - Fallback value for optional arguments
  - [quadrature](./stdlib_quadrature.html) - Numerical integration
  - [stats](./stdlib_stats.html) - Descriptive Statistics

doc/specs/stdlib_logger.md

@@ -34,6 +34,12 @@ The logger variables have the option to:
 * indent subsequent lines of the messages; and
 * format the text to fit within a maximum column width.
 
+While every effort has been made to make the code process and
+asynchronous I/O safe, it is always best to have each process write to
+its own dedicated logger file.
+For thread parallelism (e.g., with OpenMP), it is advised to put the
+logger call in a guarding region (e.g., in an OpenMP critical region).
+
 Note: Loggers of type `logger_type` normally report their messages to I/O
 units in the internal list termed `log_units`. However if `log_units`
 is empty then the messages go to the `output_unit` of the intrinsic
@@ -75,14 +81,16 @@ significant events encountered during the execution of a program.
 
 ### Private attributes
 
-| Attribute        | Type          | Description                                     | Initial value
-|------------------|---------------|-------------------------------------------------|--------------
-| `add_blank_line` | Logical       | Flag to precede output with a blank line        | `.false.`
-| `indent_lines`   | Logical       | Flag to indent subsequent lines by four columns | `.true.`
-| `log_units`      | Integer array | List of I/O units used for output               | empty
-| `max_width`      | Integer       | Maximum column width of output                  | 0
-| `time_stamp`     | Logical       | Flag to precede output by a time stamp          | `.true.`
-| `units`          | Integer       | Count of the number of active output units      | 0
+| Attribute        | Type          | Description                                     | Initial value |
+|------------------|---------------|-------------------------------------------------|--------------|
+| `add_blank_line` | Logical       | Flag to precede output with a blank line        | `.false.`    |
+| `buffer`         | Character(:)  | Buffer to build output string                   | Unallocated  |
+| `indent_lines`   | Logical       | Flag to indent subsequent lines by four columns | `.true.`     |
+| `len_buffer`     | Integer       | Number of valid characters in buffer            | 0            |
+| `log_units`      | Integer array | List of I/O units used for output               | Unallocated  |
+| `max_width`      | Integer       | Maximum column width of output                  | 0            |
+| `time_stamp`     | Logical       | Flag to precede output by a time stamp          | `.true.`     |
+| `units`          | Integer       | Count of the number of active output units      | 0            |
 
 ## The `stdlib_logger` variable
 
@@ -285,7 +293,7 @@ Pure subroutine
 
 #### Arguments
 
-`self`: shall be a scalar variable of type `logger_type`. It is an
+`self`: shall be a scalar expression of type `logger_type`. It is an
 `intent(in)` argument. It shall be the logger whose configuration is reported.
 
 `add_blank_line` (optional): shall be a scalar default logical
@@ -416,11 +424,13 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `message`: shall be a scalar default character expression. It is an
-  `intent(in)` argument.
+`intent(in)` argument.
+
+* Note `message` may have embedded new_line calls. 
 
 `module` (optional): shall be a scalar default character
   expression. It is an `intent(in)` argument. It should be the name of
@@ -497,12 +507,14 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `message`: shall be a scalar default character expression. It is an
   `intent(in)` argument.
 
+* Note `message` may have embedded new_line calls. 
+
 `module` (optional): shall be a scalar default character
   expression. It is an `intent(in)` argument. It should be the name of
   the module containing the `log_information` call.
@@ -566,12 +578,14 @@ written.
 Subroutine
 
 #### Arguments
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `message`: shall be a scalar default character expression. It is an
   `intent(in)` argument.
 
+* Note `message` may have embedded new_line calls. 
+
 `module` (optional): shall be a scalar default character
   expression. It is an `intent(in)` argument. It should be the name of
   the module containing the `log_io_error` call.
@@ -642,12 +656,14 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `message`: shall be a scalar default character expression. It is an
   `intent(in)` argument.
 
+* Note `message` may have embedded new_line calls. 
+
 `module` (optional): shall be a scalar default character
   expression. It is an `intent(in)` argument. It should be the name of
   the module containing the `log_message` call.
@@ -716,8 +732,8 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `line`: shall be a scalar default character expression. It is an
   `intent(in)` argument. It should be the line of text in which the
@@ -862,12 +878,14 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
-`intent(in)` argument. It is the logger used to send the message.
+`self`: shall be a scalar variable of type `logger_type`. It is an
+`intent(inout)` argument. It is the logger used to send the message.
 
 `message`: shall be a scalar default character expression. It is an
   `intent(in)` argument.
 
+* Note `message` may have embedded new_line calls. 
+
 `module`: (optional) shall be a scalar default character
   expression. It is an `intent(in)` argument. It should be the name of
   the module containing the `log_warning` call.
@@ -925,7 +943,7 @@ Subroutine
 
 #### Arguments
 
-`self`: shall be a scalar expression of type `logger_type`. It is an
+`self`: shall be a scalar variable of type `logger_type`. It is an
 `intent(inout)` argument. It is the logger whose `log_units` is to be
 modified.