@@ -7,13 +7,59 @@
77-- Stability : experimental
88-- Portability : GHC
99--
10−-- A socket is a handle to a protocol endpoint.
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.
1113--
12−-- This module provides APIs to read and write streams and arrays from and to
13−-- network sockets. Sockets may be connected or unconnected. Connected sockets
14−-- can only send or recv data to/from the connected endpoint, therefore, APIs
15−-- for connected sockets do not need to explicitly specify the remote endpoint.
16−-- APIs for unconnected sockets need to explicitly specify the remote endpoint.
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+-- @
1763--
1864-- = Programmer Notes
1965--
@@ -25,9 +71,23 @@
2571--
2672-- > import qualified Streamly.Network.Socket as SK
2773--
28−-- For additional, experimental APIs take a look at
29−-- "Streamly.Internal.Network.Socket" module.
74+-- = See Also
75+--
76+-- * "Streamly.Internal.Network.Socket"
77+-- * <http://hackage.haskell.org/package/network network>
3078
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+--
3191-- By design, connected socket IO APIs are similar to
3292-- "Streamly.Memory.Array" read write APIs. They are almost identical to the
3393-- sequential streaming APIs in "Streamly.Internal.FileSystem.File".