@@ -7,20 +7,28 @@
7-- Stability : experimental
7-- Stability : experimental
8-- Portability : GHC
8-- Portability : GHC
10−-- Read and write streams and arrays to and from network sockets. Socket IO
10+-- A socket is a handle to a protocol endpoint.
11−-- APIs are quite similar to "Streamly.Memory.Array" read write APIs and almost
12−-- identical to the sequential streaming APIs in "Streamly.Internal.FileSystem.File".
12+-- This module provides APIs to read and write streams and arrays to and from
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−-- Read IO requests to the socket are performed in chunks of 32KiB, this is
18+-- Read IO requests to connected stream sockets are performed in chunks of
15−-- referred to as @defaultChunkSize@ in the documentation. One IO request may
19+-- 32KiB, this is referred to as @defaultChunkSize@ in the documentation. One
16−-- or may not read the full chunk. Unless specified otherwise in the API,
20+-- IO request may or may not read the full chunk. Unless specified otherwise
17−-- writes are collected into chunks of @defaultChunkSize@ before they are
21+-- in the API, writes are collected into chunks of @defaultChunkSize@ before
18−-- written to the socket. APIs are provided to control the chunking and
22+-- they are written to the socket. APIs are provided to control the chunking
19−-- framing behavior.
23+-- and framing behavior.
21-- > import qualified Streamly.Network.Socket as SK
25-- > import qualified Streamly.Network.Socket as SK
28+-- By design, connected socket IO APIs are similar to
29+-- "Streamly.Memory.Array" read write APIs. They are almost identical to the
30+-- sequential streaming APIs in "Streamly.Internal.FileSystem.File".
24module Streamly.Network.Socket
32module Streamly.Network.Socket
26 -- * Read from connection
34 -- * Read from connection