Stability	experimental
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

GHC.Eventlog.Socket

Contents

High-level API
Legacy API

Description

This module exports the Haskell API for eventlog-socket.

To start streaming GHC eventlog events to a socket, use startWith with a socket address and options. For instance, the following code starts eventlog-socket configured to wait for a connection and then stream events to /tmp/my_app.sock.

let addr = EventlogSocketUnixAddr "/tmp/my_app.sock"
let opts = defaultEventlogSocketOpts {esoWait = True}
startWith addr opts

To register custom control commands, use registerNamespace and registerCommand. For instance, the following code registers the namespace "ping" with one command at ID 1 that prints "Ping!" when called.

pingNamespace <- registerNamespace "ping"
let pingId = CommandId 1
let pingHandler = putStrLn "Ping!"
registerCommand pingNamespace pingId pingHandler

Synopsis

startWith :: EventlogSocketAddr -> EventlogSocketOpts -> IO ()
data EventlogSocketAddr
- = EventlogSocketUnixAddr {
  - esaUnixPath :: FilePath
  }
- | EventlogSocketInetAddr {
  - esaInetHost :: String
  - esaInetPort :: String
  }
data EventlogSocketOpts
defaultEventlogSocketOpts :: EventlogSocketOpts
startFromEnv :: IO ()
fromEnv :: IO (Maybe (EventlogSocketAddr, EventlogSocketOpts))
data EventlogSocketAddrError
- = EventlogSocketAddrUnixPathTooLong FilePath
- | EventlogSocketAddrInetHostMissing String
- | EventlogSocketAddrInetPortMissing String
data Hook where
- pattern HookPostStartEventLogging :: Hook
- pattern HookPreEndEventLogging :: Hook
type HookHandler = IO ()
registerHook :: Hook -> HookHandler -> IO ()
data Namespace
newtype CommandId = CommandId Word8
type CommandHandler = IO ()
namespaceName :: Namespace -> IO String
registerNamespace :: String -> IO Namespace
registerCommand :: Namespace -> CommandId -> CommandHandler -> IO ()
data EventlogSocketControlError
- = EventlogSocketControlNamespaceTooLong String Int Int
- | EventlogSocketControlNamespaceExists String
- | EventlogSocketControlCommandExists String CommandId
- | EventlogSocketControlUnsupported
testWorkerStatus :: IO ()
testControlStatus :: IO ()
startWait :: FilePath -> IO ()
start :: FilePath -> IO ()
wait :: IO ()

High-level API

startWith :: EventlogSocketAddr -> EventlogSocketOpts -> IO () Source #

Start an eventlog-socket writer using the given socket address and options.

Since: 0.1.2.0

Configuration types

data EventlogSocketAddr Source #

A type representing the supported eventlog socket modes.

Since: 0.1.2.0

Constructors

EventlogSocketUnixAddr
Fields esaUnixPath :: FilePath Unix socket path, e.g., `"/tmp/ghc_eventlog.sock"`. Warning: Unix domain socket paths are often limited to 107 characters or less.
EventlogSocketInetAddr
Fields esaInetHost :: String TCP host or interface, e.g. `"127.0.0.1"`. esaInetPort :: String TCP port, e.g., `"4242"`.

Instances

Instances details

Show EventlogSocketAddr Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> EventlogSocketAddr -> ShowS # show :: EventlogSocketAddr -> String # showList :: [EventlogSocketAddr] -> ShowS #
Eq EventlogSocketAddr Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: EventlogSocketAddr -> EventlogSocketAddr -> Bool # (/=) :: EventlogSocketAddr -> EventlogSocketAddr -> Bool #

data EventlogSocketOpts Source #

The socket options for eventlog-socket.

To construct an instance of the socket options, use defaultEventlogSocketOpts and the fields. For instance:

myEventlogSocketOpts :: EventlogSocketOpts
myEventlogSocketOpts = defaultEventlogSocketOpts
    { esoWait = True
    }

The following socket options are available:

esoWait :: Bool: Whether or not to wait for a client to connect.
esoSndbuf ~ CInt: The size of the socket send buffer.
See the documentation for SO_SNDBUF in socket.h.
esoLinger ~ CInt: The number of seconds to linger on shutdown.
See the documentation for SO_LINGER in socket.h.

Since: 0.1.2.0

Instances

Instances details

Show EventlogSocketOpts Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> EventlogSocketOpts -> ShowS # show :: EventlogSocketOpts -> String # showList :: [EventlogSocketOpts] -> ShowS #
Eq EventlogSocketOpts Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: EventlogSocketOpts -> EventlogSocketOpts -> Bool # (/=) :: EventlogSocketOpts -> EventlogSocketOpts -> Bool #

defaultEventlogSocketOpts :: EventlogSocketOpts Source #

The default socket options for eventlog-socket.

See EventlogSocketOpts.

Since: 0.1.2.0

Configuration via environment

startFromEnv :: IO () Source #

Read the eventlog socket configuration from the environment. If this succeeds, start an eventlog-socket writer with that configuration.

Since: 0.1.2.0

fromEnv :: IO (Maybe (EventlogSocketAddr, EventlogSocketOpts)) Source #

Read the eventlog socket configuration from the environment.

Since: 0.1.2.0

data EventlogSocketAddrError Source #

The type of exceptions thrown by fromEnv.

Since: 0.1.2.0

Constructors

EventlogSocketAddrUnixPathTooLong FilePath	The found Unix domain socket path was too long.
EventlogSocketAddrInetHostMissing String	No TCP/IP port number was found, but no host name was found.
EventlogSocketAddrInetPortMissing String	A TCP/IP host name was found, but no port number was found.

Instances

Instances details

Exception EventlogSocketAddrError Source #
Instance details Defined in GHC.Eventlog.Socket Methods toException :: EventlogSocketAddrError -> SomeException # fromException :: SomeException -> Maybe EventlogSocketAddrError # displayException :: EventlogSocketAddrError -> String # backtraceDesired :: EventlogSocketAddrError -> Bool #
Show EventlogSocketAddrError Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> EventlogSocketAddrError -> ShowS # show :: EventlogSocketAddrError -> String # showList :: [EventlogSocketAddrError] -> ShowS #
Eq EventlogSocketAddrError Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: EventlogSocketAddrError -> EventlogSocketAddrError -> Bool # (/=) :: EventlogSocketAddrError -> EventlogSocketAddrError -> Bool #

Hooks

data Hook where Source #

The type of eventlog-socket hooks.

Since: 0.1.3.0

Bundled Patterns

pattern HookPostStartEventLogging :: Hook

The hook that runs after startEventLogging is called.

Since: 0.1.3.0

pattern HookPreEndEventLogging :: Hook

The hook that runs before endEventLogging is called.

Since: 0.1.3.0

Instances

Instances details

Storable Hook Source #
Instance details Defined in GHC.Eventlog.Socket Methods sizeOf :: Hook -> Int # alignment :: Hook -> Int # peekElemOff :: Ptr Hook -> Int -> IO Hook # pokeElemOff :: Ptr Hook -> Int -> Hook -> IO () # peekByteOff :: Ptr b -> Int -> IO Hook # pokeByteOff :: Ptr b -> Int -> Hook -> IO () # peek :: Ptr Hook -> IO Hook # poke :: Ptr Hook -> Hook -> IO () #
Show Hook Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> Hook -> ShowS # show :: Hook -> String # showList :: [Hook] -> ShowS #
Eq Hook Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: Hook -> Hook -> Bool # (/=) :: Hook -> Hook -> Bool #

type HookHandler = IO () Source #

The type of hook handlers.

The hook handler is evaluated once each time the control socket receives a request for the associated hook.

Warning: The hook handler must not call back into the eventlog-socket API.

Since: 0.1.3.0

registerHook Source #

Arguments

:: Hook	The hook.
-> HookHandler	The hook handler.
-> IO ()

Register an eventlog-socket hook.

Warning: Hooks cannot be unregistered and will be kept in memory until program exit.

Since: 0.1.3.0

Control commands

data Namespace Source #

The type of namespaces.

Namespaces are opaque and can only be obtained using registerNamespace.

Since: 0.1.2.0

newtype CommandId Source #

The type of command IDs.

Command IDs must be non-zero integers between 1 and 255.

Since: 0.1.2.0

Constructors

CommandId Word8

Instances

Instances details

Show CommandId Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> CommandId -> ShowS # show :: CommandId -> String # showList :: [CommandId] -> ShowS #
Eq CommandId Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: CommandId -> CommandId -> Bool # (/=) :: CommandId -> CommandId -> Bool #

type CommandHandler = IO () Source #

The type of command handlers.

The command handler is evaluated once each time the control socket receives a request for the associated command.

Warning: The command handler must not call back into the eventlog-socket API.

Since: 0.1.2.0

namespaceName :: Namespace -> IO String Source #

Get the String name for the given Namespace.

Since: 0.1.2.0

registerNamespace Source #

Arguments

:: String	The name for the namespace.
-> IO Namespace

Register an eventlog-socket control namespace with the given name and returns an opaque Namespace object.

To avoid conflicts, the namespace should use the name of the Haskell package that registers the commands.

If the size of the given name exceeds 255 bytes, this function throws EventlogSocketControlNamespaceTooLong.

If a namespace is already registered under the given name, this function throws EventlogSocketControlNamespaceExists.

If the binary was built without support for control commands, this function throws EventlogSocketControlUnsupported.

Warning: Namespaces cannot be unregistered and will be kept in memory until program exit.

Since: 0.1.2.0

registerCommand Source #

Arguments

:: Namespace	The namespace.
-> CommandId	The command ID.
-> CommandHandler	The command handler.
-> IO ()

Register an eventlog-socket control command with the given ID and handler in the given namespace.

If a command is already registered under the given ID in the given namespace, this function throws EventlogSocketControlCommandExists.

If the binary was built without support for control commands, this function throws EventlogSocketControlUnsupported.

Warning: Commands cannot be unregistered and will be kept in memory until program exit.

Since: 0.1.2.0

data EventlogSocketControlError Source #

The type of exceptions thrown by registerNamespace and registerCommand.

Since: 0.1.2.0

Constructors

EventlogSocketControlNamespaceTooLong
Fields String The requested name for the namespace. Int The size of the requested name in bytes. Int The maximum size in bytes.
EventlogSocketControlNamespaceExists
Fields String The requested name for the namespace.
EventlogSocketControlCommandExists
Fields String The name for the namespace. CommandId The requested ID for the command.
EventlogSocketControlUnsupported

Instances

Instances details

Exception EventlogSocketControlError Source #
Instance details Defined in GHC.Eventlog.Socket Methods toException :: EventlogSocketControlError -> SomeException # fromException :: SomeException -> Maybe EventlogSocketControlError # displayException :: EventlogSocketControlError -> String # backtraceDesired :: EventlogSocketControlError -> Bool #
Show EventlogSocketControlError Source #
Instance details Defined in GHC.Eventlog.Socket Methods showsPrec :: Int -> EventlogSocketControlError -> ShowS # show :: EventlogSocketControlError -> String # showList :: [EventlogSocketControlError] -> ShowS #
Eq EventlogSocketControlError Source #
Instance details Defined in GHC.Eventlog.Socket Methods (==) :: EventlogSocketControlError -> EventlogSocketControlError -> Bool # (/=) :: EventlogSocketControlError -> EventlogSocketControlError -> Bool #

Low-level API

testWorkerStatus :: IO () Source #

Test the current status of the worker thread. If it has failed, throw an IOException.

Since: 0.1.2.0

testControlStatus :: IO () Source #

Test the current status of the control thread. If it has failed, throw an IOException.

Since: 0.1.2.0

Legacy API

startWait :: FilePath -> IO () Source #

Start an eventlog-socket writer on the given Unix domain socket path and wait.

Since: 0.1.0.0

start :: FilePath -> IO () Source #

Start an eventlog-socket writer on the given Unix domain socket path.

Since: 0.1.0.0

wait :: IO () Source #

Wait for another process to connect to the eventlog socket.

Since: 0.1.0.0