say: Send textual messages to a Handle in a thread-friendly way

[ library, mit, text ] [ Propose Tags ]

Please see the README and documentation at https://www.stackage.org/package/say


[Skip to Readme]
Versions 0.1.0.0, 0.1.0.1
Change log ChangeLog.md
Dependencies base (>=4.9.1 && <5), bytestring (>=0.10.4), text (>=1.2), transformers [details]
License MIT
Copyright 2016-2018 FP Complete
Author Michael Snoyman
Maintainer michael@snoyman.com
Category Text
Home page https://github.com/fpco/say#readme
Bug tracker https://github.com/fpco/say/issues
Source repo head: git clone https://github.com/fpco/say
Uploaded by MichaelSnoyman at Wed Aug 15 07:56:05 UTC 2018
Distributions Debian:0.1.0.1, LTSHaskell:0.1.0.1, NixOS:0.1.0.1, Stackage:0.1.0.1
Downloads 1613 total (76 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-08-15 [all 1 reports]
Hackage Matrix CI

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for say-0.1.0.1

[back to package description]

say

Send textual messages to a Handle in a thread-friendly way.

Build Status Build status

The motivation for this package is described in a blog post on Haskell's Missing Concurrency Basics. The simple explanation is, when writing a line of textual data to a Handle - such as sending some messages t o ther terminal - we'd like to have the following properties:

  • Properly handle character encoding settings on the Handle
  • For reasonably sized messages, ensure that the entire message is written in one chunk to avoid interleaving data with other threads
    • This includes the trailing newline character
  • Avoid unnecessary memory allocations and copies
  • Minimize locking
  • Provide a simple API

On the last point: for the most part, you can make the following substitutions in your API usage:

  • Replace putStrLn with say
  • Replace print with sayShow
  • If you're using a String instead of Text, replace putStrLn with sayString

In addition, sayErr, sayErrString and sayErrShow work on standard error instead, and hSay, hSayString and hSayShow work on arbitrary Handles.

#!/usr/bin/env stack
-- stack --install-ghc --resolver lts-6.23 runghc --package async --package say
import Control.Concurrent.Async (mapConcurrently)
import Control.Monad            (forM_, void)
import Say                      (sayString)

worker :: Int -> IO ()
worker ident = forM_ [1..1000] $ \msg -> sayString $ concat
    [ "Hello, I am worker #"
    , show ident
    , ", and this is message #"
    , show msg
    ]

main :: IO ()
main = void $ mapConcurrently worker [1..100]