2{-# LANGUAGE BangPatterns #-}
3{-# LANGUAGE FlexibleContexts #-}
4{-# LANGUAGE MagicHash #-}
5{-# LANGUAGE RecordWildCards #-}
6{-# LANGUAGE UnboxedTuples #-}
11-- Module : Streamly.Network.Socket
12-- Copyright : (c) 2018 Harendra Kumar
15-- Maintainer : harendra.kumar@gmail.com
16-- Stability : experimental
19-- Read and write streams and arrays to and from network sockets. Socket IO
20-- APIs are quite similar to "Streamly.Mem.Array" read write APIs and almost
21-- identical to the sequential streaming APIs in "Streamly.FileSystem.File".
23-- Read IO requests to the socket are performed in chunks of 32KiB, this is
24-- referred to as @defaultChunkSize@ in the documentation. One IO request may
25-- or may not read the full chunk. Unless specified otherwise in the API,
26-- writes are collected into chunks of @defaultChunkSize@ before they are
27-- written to the socket. APIs are provided to control the chunking and
30-- > import qualified Streamly.Network.Socket as SK
33module Streamly.Network.Socket
36 -- * Read from connection
52 -- * Write to connection
63 -- reading/writing datagrams
67import Control.Concurrent (threadWaitWrite, rtsSupportsBoundThreads)
68import Control.Monad.Catch (MonadCatch, onException)
69import Control.Monad.IO.Class (MonadIO(..))
70import Control.Monad (when)
71import Data.Word (Word8)
72import Foreign.ForeignPtr (withForeignPtr)
73import Foreign.ForeignPtr.Unsafe (unsafeForeignPtrToPtr)
74import Foreign.Ptr (minusPtr, plusPtr, Ptr, castPtr)
75import Foreign.Storable (Storable(..))
76import GHC.ForeignPtr (mallocPlainForeignPtrBytes)
77import Network.Socket (Socket, sendBuf, recvBuf)
78#if MIN_VERSION_network(3,1,0)
79import Network.Socket (withFdSocket)
81import Network.Socket (fdSocket)
83import Prelude hiding (read)
85import qualified Network.Socket as Net
87import Streamly.Mem.Array.Types (Array(..))
88import Streamly.Streams.Serial (SerialT)
89import Streamly.Streams.StreamK.Type (IsStream, mkStream)
90-- import Streamly.Fold (Fold)
91-- import Streamly.String (encodeUtf8, decodeUtf8, foldLines)
93import qualified Streamly.Mem.Array as A
94import qualified Streamly.Mem.Array.Types as A hiding (flattenArrays)
95import qualified Streamly.Prelude as S
97-- | @'withSocket' socket act@ runs the computation @act@ passing the socket
98-- handle to it. The handle will be closed on exit from 'withSocket', whether
99-- by normal termination or by raising an exception. If closing the handle
100-- raises an exception, then this exception will be raised by 'withSocket'
101-- rather than any exception raised by 'act'.
102withSocket :: (MonadCatch m, MonadIO m) => Socket -> (Socket -> m ()) -> m ()
104 f sk `onException` liftIO (Net.close sk)
105 liftIO (Net.close sk)
107-------------------------------------------------------------------------------
109-------------------------------------------------------------------------------
111{-# INLINABLE readArrayUptoWith #-}
113 :: (h -> Ptr Word8 -> Int -> IO Int)
117readArrayUptoWith f size h = do
118 ptr <- mallocPlainForeignPtrBytes size
119 -- ptr <- mallocPlainForeignPtrAlignedBytes size (alignment (undefined :: Word8))
120 withForeignPtr ptr $ \p -> do
124 , aEnd = p `plusPtr` n
125 , aBound = p `plusPtr` size
127 -- XXX shrink only if the diff is significant
131-- | Read a 'ByteArray' from a file handle. If no data is available on the
132-- handle it blocks until some data becomes available. If data is available
133-- then it immediately returns that data without blocking. It reads a maximum
134-- of up to the size requested.
135{-# INLINABLE readArrayUpto #-}
136readArrayUpto :: Int -> Socket -> IO (Array Word8)
137readArrayUpto = readArrayUptoWith recvBuf
139-------------------------------------------------------------------------------
141-------------------------------------------------------------------------------
143waitWhen0 :: Int -> Socket -> IO ()
144waitWhen0 0 s = when rtsSupportsBoundThreads $
145#if MIN_VERSION_network(3,1,0)
146 withFdSocket s $ \fd -> threadWaitWrite $ fromIntegral fd
148 let fd = fdSocket s in threadWaitWrite $ fromIntegral fd
150waitWhen0 _ _ = return ()
152sendAll :: Socket -> Ptr Word8 -> Int -> IO ()
153sendAll _ _ len | len <= 0 = return ()
155 sent <- sendBuf s p len
157 -- assert (sent <= len)
158 when (sent >= 0) $ sendAll s (p `plusPtr` sent) (len - sent)
160{-# INLINABLE writeArrayWith #-}
161writeArrayWith :: Storable a
162 => (h -> Ptr Word8 -> Int -> IO ())
166writeArrayWith _ _ arr | A.length arr == 0 = return ()
167writeArrayWith f h Array{..} = withForeignPtr aStart $ \p ->
171 let p = unsafeForeignPtrToPtr aStart
174-- | Write an Array to a file handle.
177{-# INLINABLE writeArray #-}
178writeArray :: Storable a => Socket -> Array a -> IO ()
179writeArray = writeArrayWith sendAll
181-------------------------------------------------------------------------------
182-- Stream of Arrays IO
183-------------------------------------------------------------------------------
185{-# INLINABLE readArraysUptoWith #-}
186readArraysUptoWith :: (IsStream t, MonadIO m)
187 => (Int -> h -> IO (Array Word8))
188 -> Int -> h -> t m (Array Word8)
189readArraysUptoWith f size h = go
191 -- XXX use cons/nil instead
192 go = mkStream $ \_ yld _ stp -> do
193 arr <- liftIO $ f size h
198-- | @readArraysUpto size h@ reads a stream of arrays from file handle @h@.
199-- The maximum size of a single array is limited to @size@.
200-- 'fromHandleArraysUpto' ignores the prevailing 'TextEncoding' and 'NewlineMode'
202{-# INLINABLE readArraysUpto #-}
203readArraysUpto :: (IsStream t, MonadIO m)
204 => Int -> Socket -> t m (Array Word8)
205readArraysUpto = readArraysUptoWith readArrayUpto
207-- XXX read 'Array a' instead of Word8
209-- | @readArrays h@ reads a stream of arrays from file handle @h@.
210-- The maximum size of a single array is limited to @defaultChunkSize@.
211-- 'readArrays' ignores the prevailing 'TextEncoding' and 'NewlineMode'
215{-# INLINE readArrays #-}
216readArrays :: (IsStream t, MonadIO m) => Socket -> t m (Array Word8)
217readArrays = readArraysUpto A.defaultChunkSize
219-------------------------------------------------------------------------------
220-- Read File to Stream
221-------------------------------------------------------------------------------
223-- TODO for concurrent streams implement readahead IO. We can send multiple
224-- read requests at the same time. For serial case we can use async IO. We can
225-- also control the read throughput in mbps or IOPS.
228-- | @readByChunksUpto chunkSize handle@ reads a byte stream from a file
229-- handle, reads are performed in chunks of up to @chunkSize@. The stream ends
230-- as soon as EOF is encountered.
232{-# INLINE readByChunksUpto #-}
233readByChunksUpto :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
234readByChunksUpto chunkSize h = A.flattenArrays $ readArraysUpto chunkSize h
238-- read :: (IsStream t, MonadIO m, Storable a) => Handle -> t m a
240-- > read = 'readByChunks' A.defaultChunkSize
241-- | Generate a stream of elements of the given type from a file 'Handle'. The
242-- stream ends when EOF is encountered.
246read :: (IsStream t, MonadIO m) => Socket -> t m Word8
247read = A.flattenArrays . readArrays
249-- | Read a stream of Word8 from a socket, closing the socket when done.
250fromSocket :: (MonadCatch m, MonadIO m) => Socket -> SerialT m Word8
251fromSocket sk = S.finally (liftIO (Net.close sk)) (read sk)
253-------------------------------------------------------------------------------
255-------------------------------------------------------------------------------
257-- | Write a stream of arrays to a handle.
260{-# INLINE writeArrays #-}
261writeArrays :: (MonadIO m, Storable a) => Socket -> SerialT m (Array a) -> m ()
262writeArrays h m = S.mapM_ (liftIO . writeArray h) m
264-- GHC buffer size dEFAULT_FD_BUFFER_SIZE=8192 bytes.
267-- Note that if you use a chunk size less than 8K (GHC's default buffer
268-- size) then you are advised to use 'NOBuffering' mode on the 'Handle' in case you
269-- do not want buffering to occur at GHC level as well. Same thing applies to
272-- | Like 'write' but provides control over the write buffer. Output will
273-- be written to the IO device as soon as we collect the specified number of
277{-# INLINE writeByChunks #-}
278writeByChunks :: MonadIO m => Int -> Socket -> SerialT m Word8 -> m ()
279writeByChunks n h m = writeArrays h $ A.arraysOf n m
281-- > write = 'writeByChunks' A.defaultChunkSize
283-- | Write a byte stream to a file handle. Combines the bytes in chunks of size
284-- up to 'A.defaultChunkSize' before writing. Note that the write behavior
285-- depends on the 'IOMode' and the current seek position of the handle.
289write :: MonadIO m => Socket -> SerialT m Word8 -> m ()
290write = writeByChunks A.defaultChunkSize
294write :: (MonadIO m, Storable a) => Handle -> SerialT m a -> m ()
295write = toHandleWith A.defaultChunkSize
298-------------------------------------------------------------------------------
299-- IO with encoding/decoding Unicode characters
300-------------------------------------------------------------------------------
304-- > readUtf8 = decodeUtf8 . read
306-- Read a UTF8 encoded stream of unicode characters from a file handle.
309{-# INLINE readUtf8 #-}
310readUtf8 :: (IsStream t, MonadIO m) => Handle -> t m Char
311readUtf8 = decodeUtf8 . read
314-- > writeUtf8 h s = write h $ encodeUtf8 s
316-- Encode a stream of unicode characters to UTF8 and write it to the given file
317-- handle. Default block buffering applies to the writes.
320{-# INLINE writeUtf8 #-}
321writeUtf8 :: MonadIO m => Handle -> SerialT m Char -> m ()
322writeUtf8 h s = write h $ encodeUtf8 s
324-- | Write a stream of unicode characters after encoding to UTF-8 in chunks
325-- separated by a linefeed character @'\n'@. If the size of the buffer exceeds
326-- @defaultChunkSize@ and a linefeed is not yet found, the buffer is written
327-- anyway. This is similar to writing to a 'Handle' with the 'LineBuffering'
331{-# INLINE writeUtf8ByLines #-}
332writeUtf8ByLines :: (IsStream t, MonadIO m) => Handle -> t m Char -> m ()
333writeUtf8ByLines = undefined
335-- | Read UTF-8 lines from a file handle and apply the specified fold to each
336-- line. This is similar to reading a 'Handle' with the 'LineBuffering' option.
339{-# INLINE readLines #-}
340readLines :: (IsStream t, MonadIO m) => Handle -> Fold m Char b -> t m b
341readLines h f = foldLines (readUtf8 h) f
343-------------------------------------------------------------------------------
344-- Framing on a sequence
345-------------------------------------------------------------------------------
347-- | Read a stream from a file handle and split it into frames delimited by
348-- the specified sequence of elements. The supplied fold is applied on each
352{-# INLINE readFrames #-}
353readFrames :: (IsStream t, MonadIO m, Storable a)
354 => Array a -> Handle -> Fold m a b -> t m b
355readFrames = undefined -- foldFrames . read
357-- | Write a stream to the given file handle buffering up to frames separated
358-- by the given sequence or up to a maximum of @defaultChunkSize@.
361{-# INLINE writeByFrames #-}
362writeByFrames :: (IsStream t, MonadIO m, Storable a)
363 => Array a -> Handle -> t m a -> m ()
364writeByFrames = undefined
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list