MissingH-1.3.0.1: Large utility library

Copyright | Copyright (C) 2004-2011 John Goerzen
License | BSD3
Maintainer | John Goerzen <jgoerzen@complete.org>
Stability | experimental
Portability | systems with networking
Safe Haskell | None
Language | Haskell98

Network.SocketServer

Contents

- Generic Options and Types
- TCP server convenient setup
- Lower-Level Processing
- Combinators

Description

This module provides an infrastructure to simplify server design.

Written by John Goerzen, jgoerzen@complete.org

Please note: this module is designed to work with TCP, UDP, and Unix domain sockets, but only TCP sockets have been tested to date.

This module is presently under-documented. For an example of usage, please see the description of Network.FTP.Server.

Synopsis

- data InetServerOptions = InetServerOptions {
  - listenQueueSize :: Int
  - portNumber :: PortNumber
  - interface :: HostAddress
  - reuse :: Bool
  - family :: Family
  - sockType :: SocketType
  - protoStr :: String
  }
- simpleTCPOptions :: Int -> InetServerOptions
- data SocketServer = SocketServer {
  - optionsSS :: InetServerOptions
  - sockSS :: Socket
  }
- type HandlerT = Socket -> SockAddr -> SockAddr -> IO ()
- serveTCPforever :: InetServerOptions -> HandlerT -> IO ()
- setupSocketServer :: InetServerOptions -> IO SocketServer
- handleOne :: SocketServer -> HandlerT -> IO ()
- serveForever :: SocketServer -> HandlerT -> IO ()
- closeSocketServer :: SocketServer -> IO ()
- loggingHandler :: String -> Priority -> HandlerT -> HandlerT
- threadedHandler :: HandlerT -> HandlerT
- handleHandler :: (Handle -> SockAddr -> SockAddr -> IO ()) -> HandlerT

# Generic Options and Types

data InetServerOptions Source

Options for your server.

Constructors

InetServerOptions |

Fields

listenQueueSize :: Int
portNumber :: PortNumber
interface :: HostAddress
reuse :: Bool
family :: Family
sockType :: SocketType
protoStr :: String

Instances

Eq InetServerOptions Source |
Show InetServerOptions Source |

simpleTCPOptions Source

Arguments

:: Int | Port Number
-> InetServerOptions |

Get Default options. You can always modify it later.

data SocketServer Source

Constructors

SocketServer |

Fields

optionsSS :: InetServerOptions
sockSS :: Socket

Instances

Eq SocketServer Source |
Show SocketServer Source |

type HandlerT = Socket -> SockAddr -> SockAddr -> IO () Source

The main handler type.

The first parameter is the socket itself.

The second is the address of the remote endpoint.

The third is the address of the local endpoint.

# TCP server convenient setup

serveTCPforever Source

Arguments

:: InetServerOptions | Server options
-> HandlerT | Handler function
-> IO () |

Convenience function to completely set up a TCP `SocketServer` and handle all incoming requests.

This function is literally this:

    serveTCPforever options func =
        do sockserv <- setupSocketServer options
           serveForever sockserv func

# Lower-Level Processing

setupSocketServer :: InetServerOptions -> IO SocketServer Source

Takes some options and sets up the `SocketServer`. I will bind and begin listening, but will not accept any connections itself.

handleOne :: SocketServer -> HandlerT -> IO () Source

Handle one incoming request from the given `SocketServer`.

serveForever :: SocketServer -> HandlerT -> IO () Source

Handle all incoming requests from the given `SocketServer`.

closeSocketServer :: SocketServer -> IO () Source

Close the socket server. Does not terminate active handlers, if any.

# Combinators

loggingHandler Source

Arguments

:: String | Name of logger to use
-> Priority | Priority of logged messages
-> HandlerT | Handler to call after logging
-> HandlerT | Resulting handler

Log each incoming connection using the interface in System.Log.Logger.

Log when the incoming connection disconnects.

Also, log any failures that may occur in the child handler.

threadedHandler Source

Arguments

:: HandlerT | Handler to call in the new thread
-> HandlerT | Resulting handler

Handle each incoming connection in its own thread to make the server multi-tasking.

handleHandler Source

Arguments

:: (Handle -> SockAddr -> SockAddr -> IO ()) | Handler to call
-> HandlerT |

Give your handler function a Handle instead of a Socket.

The Handle will be opened with ReadWriteMode (you use one handle for both directions of the Socket). Also, it will be initialized with LineBuffering.

Unlike other handlers, the handle will be closed when the function returns. Therefore, if you are doing threading, you should to it before you call this handler.