[#176] Add an action to flush a handle (#194)

* [#176] Add an action to flush a handle

Problem: during logging one often wants data to reach destination
immediately, but logging actions provided out of the box do not
flush handles they log to.

Solution: we add a new action to `co-log-core`. This action does
not _write_ anything, but flushes the handler. We call it
`logFlush` for consistency with other `log*` actions.
It can be used as `logPrintStderr <> logFlush stderr`.

* fixup! [#191] Export showTime (#192)

* [#176] Automatically flush file handles

Problem: if we use builtin logging actions that log to files,
you will often notice that your messages appear in files with delay
due to buffering. File handles are usually block-buffered and do not
flush on newlines.
We find that behavior confusing to end users and think that it's
better to flush file handles on each log action by default.
Note that the same problem may occur with other handles (e. g. stderr)
as well, but it's less likely because they normally have line
buffering (but it's not guaranteed and is not always the case).

Solution: first of all we checked performance overhead of additional
`hFlush` call. For vanilla `putStrLn` it varies from "more than 4x"
for short messages to negligible for long messages. On average we
roughly assess it as 2x (that really depends on your use case).
Based on that we make the following trade-off:
1. Actions that write to files now also automatically flush output
buffers using `logFlush`. That's more expensive, but without flushing
behavior is quite confusing for the library users.
2. Actions that write to an arbitrary `Handle` or standard handles
do not flush by default to avoid overhead. Usually flushing will
happen automatically because of line bufferring.

* [#176] Clarify lack of flushing in default actions

* fixup! [#176] Automatically flush file handles

Author: gromakovsky

co-log-core/src/Colog/Core/IO.hs

@@ -27,11 +27,13 @@ module Colog.Core.IO
 
          -- * Various combinators
        , liftLogIO
+       , logFlush
        ) where
 
 import Colog.Core.Action (LogAction (..))
 import Control.Monad.IO.Class (MonadIO, liftIO)
-import System.IO (Handle, IOMode (AppendMode), hPrint, hPutStrLn, stderr, withFile)
+import Data.Semigroup ((<>))
+import System.IO (Handle, IOMode (AppendMode), hFlush, hPrint, hPutStrLn, stderr, withFile)
 
 
 {- $setup
@@ -43,6 +45,8 @@ import System.IO (Handle, IOMode (AppendMode), hPrint, hPutStrLn, stderr, withFi
 ----------------------------------------------------------------------------
 
 {- | Action that prints 'String' to stdout.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logStringStdout <& "foo"
 foo
@@ -53,6 +57,8 @@ logStringStdout = LogAction (liftIO . putStrLn)
 {-# SPECIALIZE logStringStdout :: LogAction IO String #-}
 
 {- | Action that prints 'String' to stderr.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logStringStderr <& "foo"
 foo
@@ -63,6 +69,8 @@ logStringStderr = logStringHandle stderr
 {-# SPECIALIZE logStringStderr :: LogAction IO String #-}
 
 {- | Action that prints 'String' to 'Handle'.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logStringHandle stderr <& "foo"
 foo
@@ -77,7 +85,7 @@ implemented in continuation-passing style because it's more efficient to open
 file only once at the start of the application and write to 'Handle' instead of
 opening file each time we need to write to it.
 
-Opens file in 'AppendMode'.
+Opens file in 'AppendMode'. Automatically flushes the output buffer.
 
 #ifndef mingw32_HOST_OS
 
@@ -88,7 +96,8 @@ foo
 #endif
 -}
 withLogStringFile :: MonadIO m => FilePath -> (LogAction m String -> IO r) -> IO r
-withLogStringFile path action = withFile path AppendMode $ action . logStringHandle
+withLogStringFile path action = withFile path AppendMode $ \handle ->
+  action (logStringHandle handle <> logFlush handle)
 {-# INLINE withLogStringFile #-}
 {-# SPECIALIZE withLogStringFile :: FilePath -> (LogAction IO String -> IO r) -> IO r #-}
 
@@ -97,6 +106,8 @@ withLogStringFile path action = withFile path AppendMode $ action . logStringHan
 ----------------------------------------------------------------------------
 
 {- | Action that prints to stdout using 'Show'.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logPrint <& 5
 5
@@ -107,6 +118,8 @@ logPrint = LogAction $ liftIO . print
 {-# SPECIALIZE logPrint :: Show a => LogAction IO a #-}
 
 {- | Action that prints to stderr using 'Show'.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logPrintStderr <& 5
 5
@@ -117,6 +130,8 @@ logPrintStderr = logPrintHandle stderr
 {-# SPECIALIZE logPrintStderr :: Show a => LogAction IO a #-}
 
 {- | Action that prints to a 'Handle' using 'Show'.
+This action does not flush the output buffer.
+If buffering mode is block buffering, the effect of this action can be delayed.
 
 >>> logPrintHandle stderr <& 5
 5
@@ -133,7 +148,8 @@ withLogPrintFile
     => FilePath
     -> (LogAction m a -> IO r)
     -> IO r
-withLogPrintFile path action = withFile path AppendMode $ action . logPrintHandle
+withLogPrintFile path action = withFile path AppendMode $ \handle ->
+  action (logPrintHandle handle <> logFlush handle)
 {-# INLINE withLogPrintFile #-}
 {-# SPECIALIZE withLogPrintFile :: Show a => FilePath -> (LogAction IO a -> IO r) -> IO r #-}
 
@@ -150,3 +166,13 @@ foo
 liftLogIO :: MonadIO m => LogAction IO msg -> LogAction m msg
 liftLogIO (LogAction action) = LogAction (liftIO . action)
 {-# INLINE liftLogIO #-}
+
+{- | This action can be used in combination with other actions to flush
+a handle every time you log anything.
+
+@since x.x.x.x
+-}
+logFlush :: MonadIO m => Handle -> LogAction m a
+logFlush handle = LogAction $ const $ liftIO $ hFlush handle
+{-# INLINE logFlush #-}
+{-# SPECIALIZE logFlush :: Handle -> LogAction IO a #-}