git.iko.soy/streamly
on bb12399 help sign in
streamly/src/Streamly/Network/Socket.hs
117 lines 4.1 kB history raw
1-- |
2-- Module : Streamly.Network.Socket
3-- Copyright : (c) 2018 Composewell Technologies
4--
5-- License : BSD3
6-- Maintainer : streamly@composewell.com
7-- Stability : experimental
8-- Portability : GHC
9--
10-- This module provides Array and stream based socket operations to connect to
11-- remote hosts, to receive connections from remote hosts, and to read and
12-- write streams and arrays of bytes to and from network sockets.
13--
14-- For basic socket types and operations please consult the @Network.Socket@
15-- module of the <http://hackage.haskell.org/package/network network> package.
16--
17-- = Examples
18--
19-- To write a server, use the 'accept' unfold to start listening for
20-- connections from clients. 'accept' supplies a stream of connected sockets.
21-- We can map an effectful action on this socket stream to handle the
22-- connections. The action would typically use socket reading and writing
23-- operations to communicate with the remote host. We can read/write a stream
24-- of bytes or a stream of chunks of bytes ('Array').
25--
26-- Following is a short example of a concurrent echo server. Please note that
27-- this example can be written more succinctly by using higher level operations
28-- from "Streamly.Network.Inet.TCP" module.
29--
30-- @
31-- {-\# LANGUAGE FlexibleContexts #-}
32--
33-- import Data.Function ((&))
34-- import Network.Socket
35-- import Streamly.Internal.Network.Socket (handleWithM)
36-- import Streamly.Network.Socket (SockSpec(..))
37--
38-- import Streamly
39-- import qualified Streamly.Prelude as S
40-- import qualified Streamly.Network.Socket as SK
41--
42-- main = do
43-- let spec = SockSpec
44-- { sockFamily = AF_INET
45-- , sockType = Stream
46-- , sockProto = defaultProtocol
47-- , sockOpts = []
48-- }
49-- addr = SockAddrInet 8090 (tupleToHostAddress (0,0,0,0))
50-- in server spec addr
51--
52-- where
53--
54-- server spec addr =
55-- S.unfold SK.accept (maxListenQueue, spec, addr) -- SerialT IO Socket
56-- & parallely . S.mapM (handleWithM echo) -- SerialT IO ()
57-- & S.drain -- IO ()
58--
59-- echo sk =
60-- S.unfold SK.readChunks sk -- SerialT IO (Array Word8)
61-- & S.fold (SK.writeChunks sk) -- IO ()
62-- @
63--
64-- = Programmer Notes
65--
66-- Read IO requests to connected stream sockets are performed in chunks of
67-- 'Streamly.Internal.Memory.Array.Types.defaultChunkSize'. Unless specified
68-- otherwise in the API, writes are collected into chunks of
69-- 'Streamly.Internal.Memory.Array.Types.defaultChunkSize' before they are
70-- written to the socket. APIs are provided to control the chunking behavior.
71--
72-- > import qualified Streamly.Network.Socket as SK
73--
74-- = See Also
75--
76-- * "Streamly.Internal.Network.Socket"
77-- * <http://hackage.haskell.org/package/network network>
79-------------------------------------------------------------------------------
80-- Internal Notes
81-------------------------------------------------------------------------------
82--
83-- A socket is a handle to a protocol endpoint.
84--
85-- This module provides APIs to read and write streams and arrays from and to
86-- network sockets. Sockets may be connected or unconnected. Connected sockets
87-- can only send or recv data to/from the connected endpoint, therefore, APIs
88-- for connected sockets do not need to explicitly specify the remote endpoint.
89-- APIs for unconnected sockets need to explicitly specify the remote endpoint.
90--
91-- By design, connected socket IO APIs are similar to
92-- "Streamly.Memory.Array" read write APIs. They are almost identical to the
93-- sequential streaming APIs in "Streamly.Internal.FileSystem.File".
94--
95module Streamly.Network.Socket
96 (
97 -- * Socket Specification
98 SockSpec(..)
100 -- * Accept Connections
101 , accept
103 -- * Read
104 , read
105 , readWithBufferOf
106 , readChunks
107 , readChunksWithBufferOf
109 -- * Write
110 , write
111 , writeWithBufferOf
112 , writeChunks
113 )
114where
116import Streamly.Internal.Network.Socket
117import Prelude hiding (read)