git.iko.soy/streamly
on 2aae2da help sign in
streamly/src/Streamly/Network/Socket.hs
128 lines 4.4 kB history raw
1-- |
2-- Module : Streamly.Network.Socket
3-- Copyright : (c) 2018 Composewell Technologies
4--
5-- License : BSD-3-Clause
6-- Maintainer : streamly@composewell.com
7-- Stability : released
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 even more succinctly by using higher level
28-- operations from "Streamly.Network.Inet.TCP" module.
29--
30-- @
31-- {-\# LANGUAGE FlexibleContexts #-}
32--
33-- import Data.Function ((&))
34-- import Network.Socket
35-- import Streamly.Network.Socket (SockSpec(..))
36--
37-- import qualified Streamly.Prelude as Stream
38-- import qualified Streamly.Network.Socket as Socket
39--
40-- main = do
41-- let spec = SockSpec
42-- { sockFamily = AF_INET
43-- , sockType = Stream
44-- , sockProto = defaultProtocol
45-- , sockOpts = []
46-- }
47-- addr = SockAddrInet 8090 (tupleToHostAddress (0,0,0,0))
48-- in server spec addr
49--
50-- where
51--
52-- server spec addr =
53-- Stream.unfold Socket.accept (maxListenQueue, spec, addr) -- ParallelT IO Socket
54-- & Stream.mapM (Socket.forSocketM echo) -- ParallelT IO ()
55-- & Stream.fromParallel -- SerialT IO ()
56-- & Stream.drain -- IO ()
57--
58-- echo sk =
59-- Stream.unfold Socket.readChunks sk -- SerialT IO (Array Word8)
60-- & Stream.fold (Socket.writeChunks sk) -- IO ()
61-- @
62--
63-- = Programmer Notes
64--
65-- Read IO requests to connected stream sockets are performed in chunks of
66-- 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize'. Unless
67-- specified otherwise in the API, writes are collected into chunks of
68-- 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize' before they are
69-- written to the socket. APIs are provided to control the chunking behavior.
70--
71-- > import qualified Streamly.Network.Socket as Socket
72--
73-- = See Also
74--
75-- * "Streamly.Internal.Network.Socket"
76-- * <http://hackage.haskell.org/package/network network>
78-------------------------------------------------------------------------------
79-- Internal Notes
80-------------------------------------------------------------------------------
81--
82-- A socket is a handle to a protocol endpoint.
83--
84-- This module provides APIs to read and write streams and arrays from and to
85-- network sockets. Sockets may be connected or unconnected. Connected sockets
86-- can only send or recv data to/from the connected endpoint, therefore, APIs
87-- for connected sockets do not need to explicitly specify the remote endpoint.
88-- APIs for unconnected sockets need to explicitly specify the remote endpoint.
89--
90-- By design, connected socket IO APIs are similar to
91-- "Streamly.Data.Array.Foreign" read write APIs. They are almost identical to the
92-- sequential streaming APIs in "Streamly.Internal.FileSystem.File".
93--
94module Streamly.Network.Socket
95 (
96 -- * Socket Specification
97 SockSpec(..)
99 -- * Accept Connections
100 , accept
102 -- * Read
103 , read
104 , readWith
105 , readChunks
106 , readChunksWith
107 , readChunk
109 -- * Write
110 , write
111 , writeWith
112 , writeChunks
113 , writeChunksWith
114 , writeChunk
116 -- * Exceptions
117 , forSocketM
119 -- * Deprecated
120 , readWithBufferOf
121 , readChunksWithBufferOf
122 , writeWithBufferOf
123 , writeChunksWithBufferOf
124 )
125where
127import Streamly.Internal.Network.Socket
128import Prelude hiding (read)