@@ -11,20 +11,25 @@
1111
1212module Streamly.Internal.Network.Inet.TCP
1313 (
14+ -- * Setup
15+ -- | To execute the code examples provided in this module in ghci, please
16+ -- run the following commands first.
17+ --
18+ -- $setup
19+
1420 -- * TCP Servers
1521 -- ** Streams
16− acceptOnAddr
22+ accept
23+ , acceptLocal
24+ , acceptOnAddr
1725 , acceptOnAddrWith
18− , acceptOnPort
19− -- , acceptOnPortWith
20− , acceptOnPortLocal
2126
2227 -- ** Unfolds
28+ , acceptor
29+ , acceptorLocal
30+ , acceptorWith
2331 , acceptorOnAddr
2432 , acceptorOnAddrWith
25− , acceptorOnPort
26− , acceptorOnPortWith
27− , acceptorOnPortLocal
2833
2934 -- * TCP clients
3035 -- | IP Address based operations.
@@ -89,6 +94,10 @@ module Streamly.Internal.Network.Inet.TCP
8994 , datagrams
9095 , datagramsOn
9196 -}
97+
98+ -- * Deprecated
99+ , acceptorOnPort
100+ , acceptorOnPortLocal
92101 )
93102where
94103
@@ -113,7 +122,7 @@ import Streamly.Data.Stream (Stream)
113122import Streamly.Internal.Data.Tuple.Strict (Tuple'(..))
114123import Streamly.Data.MutByteArray (Unbox)
115124import Streamly.Data.Unfold (Unfold)
116−import Streamly.Internal.Network.Socket (SockSpec(..), accept, acceptor)
125+import Streamly.Internal.Network.Socket (SockSpec(..))
117126import Streamly.Internal.System.IO (defaultChunkSize)
118127
119128import qualified Control.Monad.Catch as MC
@@ -124,12 +133,17 @@ import qualified Streamly.Data.Fold as FL
124133import qualified Streamly.Data.Stream as S
125134import qualified Streamly.Data.Unfold as UF
126135import qualified Streamly.Internal.Data.Array as A (pinnedChunksOf)
127−import qualified Streamly.Internal.Data.Unfold as UF (first, bracketIO)
136+import qualified Streamly.Internal.Data.Unfold as UF (bracketIO)
128137import qualified Streamly.Internal.Data.Fold as FL (Step(..), reduce)
129138
130139import qualified Streamly.Internal.Data.Stream.Exception.Lifted as S (bracket)
131140import qualified Streamly.Internal.Network.Socket as ISK
132− (chunkReader, putBytes, putChunks, read, readChunks, writeChunks)
141+
142+-- $setup
143+-- >>> :m
144+--
145+-- >>> import qualified Streamly.Data.Unfold as Unfold
146+-- >>> import qualified Streamly.Network.Inet.TCP as TCP
133147
134148-------------------------------------------------------------------------------
135149-- Accept (unfolds)
@@ -140,7 +154,7 @@ acceptorOnAddrWith
140154 :: MonadIO m
141155 => [(SocketOption, Int)]
142156 -> Unfold m ((Word8, Word8, Word8, Word8), PortNumber) Socket
143−acceptorOnAddrWith opts = UF.lmap f acceptor
157+acceptorOnAddrWith opts = UF.lmap f ISK.acceptor
144158 where
145159 f (addr, port) =
146160 (maxListenQueue
@@ -163,36 +177,50 @@ acceptorOnAddr
163177 => Unfold m ((Word8, Word8, Word8, Word8), PortNumber) Socket
164178acceptorOnAddr = acceptorOnAddrWith []
165179
166−{-# INLINE acceptorOnPortWith #-}
167−acceptorOnPortWith :: MonadIO m
180+{-# INLINE acceptorWith #-}
181+acceptorWith :: MonadIO m
168182 => [(SocketOption, Int)]
169183 -> Unfold m PortNumber Socket
170−acceptorOnPortWith opts = UF.first (0,0,0,0) (acceptorOnAddrWith opts)
184+acceptorWith opts = UF.first (0,0,0,0) (acceptorOnAddrWith opts)
171185
172186-- | Like 'acceptorOnAddr' but binds on the IPv4 address @0.0.0.0@ i.e. on all
173187-- IPv4 addresses/interfaces of the machine and listens for TCP connections on
174188-- the specified port.
175189--
176−-- > acceptorOnPort = UF.first acceptorOnAddr (0,0,0,0)
190+-- >>> acceptor = Unfold.first (0,0,0,0) TCP.acceptorOnAddr
177191--
192+{-# INLINE acceptor #-}
193+acceptor :: MonadIO m => Unfold m PortNumber Socket
194+acceptor = UF.first (0,0,0,0) acceptorOnAddr
195+
196+{-# DEPRECATED acceptorOnPort "Use \"acceptor\" instead." #-}
178197{-# INLINE acceptorOnPort #-}
179198acceptorOnPort :: MonadIO m => Unfold m PortNumber Socket
180−acceptorOnPort = UF.first (0,0,0,0) acceptorOnAddr
199+acceptorOnPort = acceptor
181200
182−-- | Like 'acceptorOnAddr' but binds on the localhost IPv4 address @127.0.0.1@.
183−-- The server can only be accessed from the local host, it cannot be accessed
184−-- from other hosts on the network.
201+-- | Like 'acceptor' but binds on the localhost IPv4 address @127.0.0.1@. The
202+-- server can only be accessed from the local host, it cannot be accessed from
203+-- other hosts on the network.
185204--
186−-- > acceptorOnPortLocal = UF.first acceptorOnAddr (127,0,0,1)
205+-- >>> acceptorLocal = Unfold.first (127,0,0,1) TCP.acceptorOnAddr
187206--
207+{-# INLINE acceptorLocal #-}
208+acceptorLocal :: MonadIO m => Unfold m PortNumber Socket
209+acceptorLocal = UF.first (127,0,0,1) acceptorOnAddr
210+
211+{-# DEPRECATED acceptorOnPortLocal "Use \"acceptorLocal\" instead." #-}
188212{-# INLINE acceptorOnPortLocal #-}
189213acceptorOnPortLocal :: MonadIO m => Unfold m PortNumber Socket
190−acceptorOnPortLocal = UF.first (127,0,0,1) acceptorOnAddr
214+acceptorOnPortLocal = acceptorLocal
191215
192216-------------------------------------------------------------------------------
193217-- Accept (streams)
194218-------------------------------------------------------------------------------
195219
220+-- | Like 'acceptOnAddr' but with the ability to specify a list of socket
221+-- options.
222+--
223+-- /Pre-release/
196224{-# INLINE acceptOnAddrWith #-}
197225acceptOnAddrWith
198226 :: MonadIO m
@@ -201,7 +229,7 @@ acceptOnAddrWith
201229 -> PortNumber
202230 -> Stream m Socket
203231acceptOnAddrWith opts addr port =
204− accept maxListenQueue SockSpec
232+ ISK.accept maxListenQueue SockSpec
205233 { sockFamily = AF_INET
206234 , sockType = Stream
207235 , sockProto = defaultProtocol
@@ -209,8 +237,9 @@ acceptOnAddrWith opts addr port =
209237 }
210238 (SockAddrInet port (tupleToHostAddress addr))
211239
212−-- | Like 'accept' but binds on the specified IPv4 address of the machine
213−-- and listens for TCP connections on the specified port.
240+-- | Like 'accept' but binds on the specified IPv4 address.
241+--
242+-- >>> acceptOnAddr = TCP.acceptOnAddrWith []
214243--
215244-- /Pre-release/
216245{-# INLINE acceptOnAddr #-}
@@ -221,27 +250,27 @@ acceptOnAddr
221250 -> Stream m Socket
222251acceptOnAddr = acceptOnAddrWith []
223252
224−-- | Like 'accept' but binds on the IPv4 address @0.0.0.0@ i.e. on all
225−-- IPv4 addresses/interfaces of the machine and listens for TCP connections on
226−-- the specified port.
253+-- | Start a TCP stream server that binds on the IPV4 address @0.0.0.0@ and
254+-- listens for TCP connections from remote hosts on the specified server port.
255+-- The server generates a stream of connected sockets.
227256--
228−-- > acceptOnPort = acceptOnAddr (0,0,0,0)
257+-- >>> accept = TCP.acceptOnAddr (0,0,0,0)
229258--
230259-- /Pre-release/
231−{-# INLINE acceptOnPort #-}
232−acceptOnPort :: MonadIO m => PortNumber -> Stream m Socket
233−acceptOnPort = acceptOnAddr (0,0,0,0)
260+{-# INLINE accept #-}
261+accept :: MonadIO m => PortNumber -> Stream m Socket
262+accept = acceptOnAddr (0,0,0,0)
234263
235264-- | Like 'accept' but binds on the localhost IPv4 address @127.0.0.1@.
236265-- The server can only be accessed from the local host, it cannot be accessed
237266-- from other hosts on the network.
238267--
239−-- > acceptOnPortLocal = acceptOnAddr (127,0,0,1)
268+-- >>> acceptLocal = TCP.acceptOnAddr (127,0,0,1)
240269--
241270-- /Pre-release/
242−{-# INLINE acceptOnPortLocal #-}
243−acceptOnPortLocal :: MonadIO m => PortNumber -> Stream m Socket
244−acceptOnPortLocal = acceptOnAddr (127,0,0,1)
271+{-# INLINE acceptLocal #-}
272+acceptLocal :: MonadIO m => PortNumber -> Stream m Socket
273+acceptLocal = acceptOnAddr (127,0,0,1)
245274
246275-------------------------------------------------------------------------------
247276-- TCP Clients