Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Improve counter and gauge documentation

  • Loading branch information...
commit 3cf252ee96d6578e7e30f4da28dfc95421838785 1 parent e59d03f
Johan Tibell authored
31 System/Remote/Counter.hs
View
@@ -1,15 +1,13 @@
{-# LANGUAGE BangPatterns #-}
-- | This module defines a type for mutable, integer-valued counters.
--- All operations on counters are thread-safe.
+-- Counters are monotonically increasing and can be used to track
+-- e.g. the number of requests served since program start. All
+-- operations on counters are thread-safe.
module System.Remote.Counter
(
Counter
, inc
- , dec
, add
- , subtract
- , set
- , modify
) where
import Data.IORef (atomicModifyIORef)
@@ -23,31 +21,8 @@ inc (C ref) = do
!_ <- atomicModifyIORef ref $ \ n -> let n' = n + 1 in (n', n')
return ()
--- | Decrease the counter by one.
-dec :: Counter -> IO ()
-dec (C ref) = do
- !_ <- atomicModifyIORef ref $ \ n -> let n' = n - 1 in (n', n')
- return ()
-
-- | Increase the counter by the given amount.
add :: Counter -> Int -> IO ()
add (C ref) i = do
!_ <- atomicModifyIORef ref $ \ n -> let n' = n + i in (n', n')
return ()
-
--- | Decrease the counter by the given amount.
-subtract :: Counter -> Int -> IO ()
-subtract (C ref) i = do
- !_ <- atomicModifyIORef ref $ \ n -> let n' = n - i in (n', n')
- return ()
-
--- | Set the counter to the given value.
-set :: Counter -> Int -> IO ()
-set (C ref) !i = atomicModifyIORef ref $ \ _ -> (i, ())
-
--- | Set the counter to the result of applying the given function to
--- the value.
-modify :: (Int -> Int) -> Counter -> IO ()
-modify f (C ref) = do
- !_ <- atomicModifyIORef ref $ \ i -> let i' = f i in (i', i')
- return ()
4 System/Remote/Gauge.hs
View
@@ -1,6 +1,8 @@
{-# LANGUAGE BangPatterns #-}
-- | This module defines a type for mutable, integer-valued gauges.
--- All operations on gauges are thread-safe.
+-- Gauges are variable values and can be used to track e.g. the
+-- current number of concurrent connections. All operations on gauges
+-- are thread-safe.
module System.Remote.Gauge
(
Gauge
19 System/Remote/Monitoring.hs
View
@@ -179,8 +179,9 @@ serverThreadId = threadId
-- either a numeric network address (dotted quad for IPv4,
-- colon-separated hex for IPv6) or a hostname (e.g. \"localhost\").
-- The client can control the Content-Type used in responses by
--- setting the Accept header. At the moment two content types are
--- available: \"application\/json\" and \"text\/html\".
+-- setting the Accept header. At the moment three content types are
+-- available: \"application\/json\", \"text\/html\", and
+-- \"text\/plain\".
forkServer :: S.ByteString -- ^ Host to listen on (e.g. \"localhost\")
-> Int -- ^ Port to listen on (e.g. 8000)
-> IO Server
@@ -201,9 +202,12 @@ forkServer host port = do
-- $userdefined
-- The monitoring server can store and serve user-defined,
--- integer-valued counters and gauges. Each counter or gauge is
--- associated with a name, which is used when the counter or gauge is
--- displayed in the UI or returned in a JSON object.
+-- integer-valued counters and gauges. A counter is a monotonically
+-- increasing value (e.g. TCP connections established since program
+-- start). A gauge is a variable value (e.g. the current number of
+-- concurrent connections.) Each counter or gauge is associated with
+-- a name, which is used when the counter or gauge is displayed in the
+-- UI or returned in a JSON object.
--
-- Even though it's technically possible to have a counter and a gauge
-- with the same name, associated with the same server, it's not
@@ -212,7 +216,7 @@ forkServer host port = do
--
-- To create and use a counter, simply call 'getCounter' to create it
-- and then call e.g. 'Counter.inc' or 'Counter.add' to modify its
--- value. Example:
+-- value. Example:
--
-- > main = do
-- > handle <- forkServer "localhost" 8000
@@ -221,6 +225,9 @@ forkServer host port = do
-- > inc counter
-- > loop
-- > loop
+--
+-- To create a guage, use 'getGauge' instead of 'getCounter' and then
+-- call e.g. 'Gauge.set' or 'Gauge.modify'.
class Ref r where
new :: IO r
Please sign in to comment.
Something went wrong with that request. Please try again.