base-4.6.0.1: Basic libraries

Safe Haskell | Trustworthy

GHC.Event

Contents

- Types
- Creation
- Running
  - Stepwise running
- Registering interest in I/O events
- Registering interest in timeout events

Description

This module provides scalable event notification for file descriptors and timeouts.

This module should be considered GHC internal.

- ---------------------------------------------------------------------------

Synopsis

- data EventManager
- new :: IO EventManager
- getSystemEventManager :: IO (Maybe EventManager)
- loop :: EventManager -> IO ()
- step :: EventManager -> TimeoutQueue -> IO (Bool, TimeoutQueue)
- shutdown :: EventManager -> IO ()
- data Event
- evtRead :: Event
- evtWrite :: Event
- type IOCallback = FdKey -> Event -> IO ()
- data FdKey
- registerFd :: EventManager -> IOCallback -> Fd -> Event -> IO FdKey
- registerFd_ :: EventManager -> IOCallback -> Fd -> Event -> IO (FdKey, Bool)
- unregisterFd :: EventManager -> FdKey -> IO ()
- unregisterFd_ :: EventManager -> FdKey -> IO Bool
- closeFd :: EventManager -> (Fd -> IO ()) -> Fd -> IO ()
- type TimeoutCallback = IO ()
- data TimeoutKey
- registerTimeout :: EventManager -> Int -> TimeoutCallback -> IO TimeoutKey
- updateTimeout :: EventManager -> TimeoutKey -> Int -> IO ()
- unregisterTimeout :: EventManager -> TimeoutKey -> IO ()

# Types

data EventManager

The event manager state.

# Creation

new :: IO EventManager

Create a new event manager.

getSystemEventManager :: IO (Maybe EventManager)

Retrieve the system event manager.

This function always returns `Just` the system event manager when using the threaded RTS and `Nothing` otherwise.

# Running

loop :: EventManager -> IO ()

Start handling events. This function loops until told to stop, using `shutdown`.

Note: This loop can only be run once per `EventManager`, as it closes all of its control resources when it finishes.

## Stepwise running

step :: EventManager -> TimeoutQueue -> IO (Bool, TimeoutQueue)

shutdown :: EventManager -> IO ()

Asynchronously shuts down the event manager, if running.

# Registering interest in I/O events

data Event

An I/O event.

Instances

Eq Event |
Show Event |
Monoid Event |

evtRead :: Event

Data is available to be read.

evtWrite :: Event

The file descriptor is ready to accept a write.

type IOCallback = FdKey -> Event -> IO ()

Callback invoked on I/O events.

data FdKey

A file descriptor registration cookie.

Instances

Eq FdKey |
Show FdKey |

registerFd :: EventManager -> IOCallback -> Fd -> Event -> IO FdKey

`registerFd mgr cb fd evs` registers interest in the events `evs` on the file descriptor `fd`. `cb` is called for each event that occurs. Returns a cookie that can be handed to `unregisterFd`.

registerFd_ :: EventManager -> IOCallback -> Fd -> Event -> IO (FdKey, Bool)

Register interest in the given events, without waking the event manager thread. The `Bool` return value indicates whether the event manager ought to be woken.

unregisterFd :: EventManager -> FdKey -> IO ()

Drop a previous file descriptor registration.

unregisterFd_ :: EventManager -> FdKey -> IO Bool

Drop a previous file descriptor registration, without waking the event manager thread. The return value indicates whether the event manager ought to be woken.

closeFd :: EventManager -> (Fd -> IO ()) -> Fd -> IO ()

Close a file descriptor in a race-safe way.

# Registering interest in timeout events

type TimeoutCallback = IO ()

Callback invoked on timeout events.

data TimeoutKey

A timeout registration cookie.

Instances

Eq TimeoutKey |

registerTimeout :: EventManager -> Int -> TimeoutCallback -> IO TimeoutKey

Register a timeout in the given number of microseconds. The returned `TimeoutKey` can be used to later unregister or update the timeout. The timeout is automatically unregistered after the given time has passed.

updateTimeout :: EventManager -> TimeoutKey -> Int -> IO ()

Update an active timeout to fire in the given number of microseconds.

unregisterTimeout :: EventManager -> TimeoutKey -> IO ()

Unregister an active timeout.