network-simple-0.4.0.5: Simple network sockets usage patterns.

Safe HaskellNone
LanguageHaskell98

Network.Simple.TCP

Contents

Description

This module exports functions that abstract simple TCP Socket usage patterns.

This module uses MonadIO and MonadMask extensively so that you can reuse these functions in monads other than IO. However, if you don't care about any of that, just pretend you are using the IO monad all the time and everything will work as expected.

Synopsis

Introduction to TCP networking

This introduction aims to give you a overly simplified overview of some concepts you need to know about TCP sockets in order to make effective use of this module.

There are two ends in a single TCP connection: one is the TCP «server» and the other is the TCP «client». Each end is uniquely identified by an IP address and a TCP port pair, and each end knows the IP address and TCP port of the other end. Each end can send and receive data to and from the other end.

A TCP server, once «bound» to a well-known IP address and TCP port, starts «listening» for incoming connections from TCP clients to such bound IP address and TCP port. When a TCP client attempts to connect to the TCP server, the TCP server must «accept» the incoming connection in order to start exchanging data with the remote end. A single TCP server can sequentially accept many incoming connections, possibly handling each one concurrently.

A TCP client can «connect» to a well-known IP address and TCP port previously bound by a listening TCP server willing to accept new incoming connections. Once the connection is established, the TCP client can immediately start exchanging data with the TCP server. The TCP client is randomly assigned a TCP port when connecting, and its IP address is selected by the operating system so that it is reachable from the remote end.

The TCP client a and the TCP server can be running in the same host or in different hosts.

Client side

Here's how you could run a TCP client:

connect "www.example.org" "80" $ \(connectionSocket, remoteAddr) -> do
  putStrLn $ "Connection established to " ++ show remoteAddr
  -- Now you may use connectionSocket as you please within this scope,
  -- possibly using recv and send to interact with the remote end.

connect #

Arguments

:: (MonadIO m, MonadMask m) 
=> HostName

Server hostname.

-> ServiceName

Server service port.

-> ((Socket, SockAddr) -> m r)

Computation taking the communication socket and the server address.

-> m r 

Connect to a TCP server and use the connection.

The connection socket is closed when done or in case of exceptions.

If you prefer to acquire and close the socket yourself, then use connectSock and closeSock.

Server side

Here's how you can run a TCP server that handles in different threads each incoming connection to port 8000 at IPv4 address 127.0.0.1:

serve (Host "127.0.0.1") "8000" $ \(connectionSocket, remoteAddr) -> do
  putStrLn $ "TCP connection established from " ++ show remoteAddr
  -- Now you may use connectionSocket as you please within this scope,
  -- possibly using recv and send to interact with the remote end.

If you need more control on the way your server runs, then you can use more advanced functions such as listen, accept and acceptFork.

serve #

Arguments

:: MonadIO m 
=> HostPreference

Preferred host to bind.

-> ServiceName

Service port to bind.

-> ((Socket, SockAddr) -> IO ())

Computation to run in a different thread once an incoming connection is accepted. Takes the connection socket and remote end address.

-> m () 

Start a TCP server that accepts incoming connections and handles them concurrently in different threads.

Any acquired network resources are properly closed and discarded when done or in case of exceptions.

Note: This function performs listen and acceptFork, so you don't need to perform those manually.

Listening

listen #

Arguments

:: (MonadIO m, MonadMask m) 
=> HostPreference

Preferred host to bind.

-> ServiceName

Service port to bind.

-> ((Socket, SockAddr) -> m r)

Computation taking the listening socket and the address it's bound to.

-> m r 

Bind a TCP listening socket and use it.

The listening socket is closed when done or in case of exceptions.

If you prefer to acquire and close the socket yourself, then use bindSock, closeSock and the listen function from Network.Socket instead.

Note: maxListenQueue is typically 128, which is too small for high performance servers. So, we use the maximum between maxListenQueue and 2048 as the default size of the listening queue. The NoDelay and ReuseAddr options are set on the socket.

Accepting

accept #

Arguments

:: (MonadIO m, MonadMask m) 
=> Socket

Listening and bound socket.

-> ((Socket, SockAddr) -> m r)

Computation to run once an incoming connection is accepted. Takes the connection socket and remote end address.

-> m r 

Accept a single incoming connection and use it.

The connection socket is closed when done or in case of exceptions.

acceptFork #

Arguments

:: MonadIO m 
=> Socket

Listening and bound socket.

-> ((Socket, SockAddr) -> IO ())

Computation to run in a different thread once an incoming connection is accepted. Takes the connection socket and remote end address.

-> m ThreadId 

Accept a single incoming connection and use it in a different thread.

The connection socket is closed when done or in case of exceptions.

Utils

recv :: MonadIO m => Socket -> Int -> m (Maybe ByteString) #

Read up to a limited number of bytes from a socket.

Returns Nothing if the remote end closed the connection or end-of-input was reached. The number of returned bytes might be less than the specified limit.

send :: MonadIO m => Socket -> ByteString -> m () #

Writes a ByteString to the socket.

sendLazy :: MonadIO m => Socket -> ByteString -> m () #

Writes a lazy ByteString to the socket.

sendMany :: MonadIO m => Socket -> [ByteString] -> m () #

Writes the given list of ByteStrings to the socket. This is faster than sending them individually.

Low level support

bindSock :: MonadIO m => HostPreference -> ServiceName -> m (Socket, SockAddr) #

Obtain a Socket bound to the given host name and TCP service port.

The obtained Socket should be closed manually using closeSock when it's not needed anymore.

Prefer to use listen if you will be listening on this socket and using it within a limited scope, and would like it to be closed immediately after its usage or in case of exceptions.

connectSock :: MonadIO m => HostName -> ServiceName -> m (Socket, SockAddr) #

Obtain a Socket connected to the given host and TCP service port.

The obtained Socket should be closed manually using closeSock when it's not needed anymore, otherwise you risk having the socket open for much longer than needed.

Prefer to use connect if you will be using the socket within a limited scope and would like it to be closed immediately after its usage or in case of exceptions.

closeSock :: MonadIO m => Socket -> m () #

Close the Socket.

Note to Windows users

withSocketsDo :: IO a -> IO a #

With older versions of the network library on Windows operating systems, the networking subsystem must be initialised using withSocketsDo before any networking operations can be used. eg.

main = withSocketsDo $ do {...}

It is fine to nest calls to withSocketsDo, and to perform networking operations after withSocketsDo has returned.

In newer versions of the network library it is only necessary to call withSocketsDo if you are calling the MkSocket constructor directly. However, for compatibility with older versions on Windows, it is good practice to always call withSocketsDo (it's very cheap).

Types

data HostPreference #

Preferred host to bind.

Constructors

HostAny

Any available host.

HostIPv4

Any available IPv4 host.

HostIPv6

Any available IPv6 host.

Host HostName

An explicit host name.

Instances

Re-exported from Network.Socket

type HostName = String #

Either a host name e.g., "haskell.org" or a numeric host address string consisting of a dotted decimal IPv4 address or an IPv6 address e.g., "192.168.0.1".

type ServiceName = String #

data Socket :: * #

Represents a socket. The fields are, respectively:

  • File descriptor
  • Socket family
  • Socket type
  • Protocol number
  • Status flag

If you are calling the MkSocket constructor directly you should ensure you have called withSocketsDo and that the file descriptor is in non-blocking mode. See setNonBlockIfNeeded.

Instances

Eq Socket 

Methods

(==) :: Socket -> Socket -> Bool #

(/=) :: Socket -> Socket -> Bool #

Show Socket 

data SockAddr :: * #

The existence of a constructor does not necessarily imply that that socket address type is supported on your system: see isSupportedSockAddr.

Instances