Z.IO.Buffered

This module provides low level buffered IO interface, it's recommended to check higher level streaming interface Z.IO.BIO first as it provides more features.

Input & Output device

class Input i where

Input device

readInput should return 0 on EOF.

Methods

readInput :: HasCallStack => i -> Ptr Word8 -> Int -> IO Int

Instances

Input StdStream

Defined in Z.IO.StdStream

Methods

readInput :: StdStream -> Ptr Word8 -> Int -> IO Int

Input FilePtrT

Defined in Z.IO.FileSystem.Threaded

Methods

readInput :: FilePtrT -> Ptr Word8 -> Int -> IO Int

Input File

Defined in Z.IO.FileSystem.Threaded

Methods

readInput :: File -> Ptr Word8 -> Int -> IO Int

Input FilePtr

Defined in Z.IO.FileSystem

Methods

readInput :: FilePtr -> Ptr Word8 -> Int -> IO Int

Input File

Defined in Z.IO.FileSystem

Methods

readInput :: File -> Ptr Word8 -> Int -> IO Int

Input UVStream

Defined in Z.IO.UV.UVStream

Methods

readInput :: UVStream -> Ptr Word8 -> Int -> IO Int

class Output o where

Output device

writeOutput should not return until all data are written (may not necessarily flushed to hardware, that should be done in device specific way).

Methods

writeOutput :: HasCallStack => o -> Ptr Word8 -> Int -> IO ()

Instances

Output StdStream

Defined in Z.IO.StdStream

Methods

writeOutput :: StdStream -> Ptr Word8 -> Int -> IO ()

Output FilePtrT

Defined in Z.IO.FileSystem.Threaded

Methods

writeOutput :: FilePtrT -> Ptr Word8 -> Int -> IO ()

Output File

Defined in Z.IO.FileSystem.Threaded

Methods

writeOutput :: File -> Ptr Word8 -> Int -> IO ()

Output FilePtr

Defined in Z.IO.FileSystem

Methods

writeOutput :: FilePtr -> Ptr Word8 -> Int -> IO ()

Output File

Defined in Z.IO.FileSystem

Methods

writeOutput :: File -> Ptr Word8 -> Int -> IO ()

Output UVStream

Defined in Z.IO.UV.UVStream

Methods

writeOutput :: UVStream -> Ptr Word8 -> Int -> IO ()

Buffered Input

data BufferedInput

Input device with buffer, NOT THREAD SAFE!

• A BufferedInput should not be used in multiple threads, there's no locking mechanism to protect buffering state.
• A Input device should only be used with a single BufferedInput, If multiple BufferedInput s are opened on a same Input device, the behaviour is undefined.

bufInput :: BufferedInput -> HasCallStack => Ptr Word8 -> Int -> IO Int

newBufferedInput :: Input i => i -> IO BufferedInput

Open a new buffered input with defaultChunkSize as buffer size.

newBufferedInput'

Arguments

:: Input i

=> Int

Input buffer size

-> i

-> IO BufferedInput

Open a new buffered input with given buffer size, e.g. defaultChunkSize.

readBuffer :: HasCallStack => BufferedInput -> IO Bytes

Request bytes chunk from BufferedInput.

The buffering logic is quite simple:

If we have pushed back bytes, directly return it, otherwise we read using buffer size. If we read N bytes, and N is larger than half of the buffer size, then we freeze buffer and return, otherwise we copy buffer into result and reuse buffer afterward.

readBufferText :: HasCallStack => BufferedInput -> IO Text

Request UTF8 Text chunk from BufferedInput.

The buffer size must be larger than 4 bytes to guarantee decoding progress.

unReadBuffer :: HasCallStack => Bytes -> BufferedInput -> IO ()

Push bytes back into buffer(if not empty).

readParser :: HasCallStack => Parser a -> BufferedInput -> IO (Either ParseError a)

Read buffer and parse with Parser.

This function will continuously draw data from input before parsing finish. Unconsumed bytes will be returned to buffer.

Either during parsing or before parsing, reach EOF will result in ParseError.

readExactly :: HasCallStack => Int -> BufferedInput -> IO Bytes

Read N bytes(may be smaller than N if EOF reached).

If EOF reached before N bytes read, trailing bytes will be returned.

readExactly' :: HasCallStack => Int -> BufferedInput -> IO Bytes

Read exactly N bytes

If EOF reached before N bytes read, a IncompleteInput will be thrown

readToMagic :: HasCallStack => Word8 -> BufferedInput -> IO Bytes

Read until reach a magic bytes, return bytes(including the magic bytes)

If EOF is reached before meet a magic byte, partial bytes are returned.

readToMagic' :: HasCallStack => Word8 -> BufferedInput -> IO Bytes

Read until reach a magic bytes, return bytes(including the magic bytes)

If EOF is reached before meet a magic byte, a IncompleteInput will be thrown.

readLine :: HasCallStack => BufferedInput -> IO (Maybe Bytes)

Read to a linefeed ('n' or 'rn'), return Bytes before it.

Return bytes don't include linefeed, empty bytes indicate empty line, Nothing indicate EOF. If EOF is reached before meet a line feed, partial line is returned.

readLine' :: HasCallStack => BufferedInput -> IO (Maybe Bytes)

Read to a linefeed ('n' or 'rn'), return Bytes before it.

Return bytes don't include linefeed, empty bytes indicate empty line, Nothing indicate EOF. If EOF reached before meet a line feed, a IncompleteInput will be thrown.

readAll :: HasCallStack => BufferedInput -> IO [Bytes]

Read all chunks from a BufferedInput.

This function will loop read until meet EOF(Input device return empty), Useful for reading small file into memory.

readAll' :: HasCallStack => BufferedInput -> IO Bytes

Read all chunks from a BufferedInput, and concat chunks together.

This function will loop read until meet EOF(Input device return empty), Useful for reading small file into memory.

Buffered Output

data BufferedOutput

Output device with buffer, NOT THREAD SAFE!

• A BufferedOutput should not be used in multiple threads, there's no locking mechanism to protect buffering state.
• A Output device should only be used with a single BufferedOutput, If multiple BufferedOutput s are opened on a same BufferedOutput device, the output will be interleaved.

bufOutput :: BufferedOutput -> HasCallStack => Ptr Word8 -> Int -> IO ()

newBufferedOutput :: Output o => o -> IO BufferedOutput

Open a new buffered output with defaultChunkSize as buffer size.

newBufferedOutput'

Arguments

:: Output o

=> Int

Output buffer size

-> o

-> IO BufferedOutput

Open a new buffered output with given buffer size, e.g. defaultChunkSize.

writeBuffer :: HasCallStack => BufferedOutput -> Bytes -> IO ()

Write Bytes into buffered handle.

• If buffer is empty and bytes are larger than half of buffer, directly write bytes, otherwise copy bytes to buffer.
• If buffer is not empty, then copy bytes to buffer if it can hold, otherwise write buffer first, then try again.

writeBuilder :: HasCallStack => BufferedOutput -> Builder a -> IO ()

Directly write Builder into buffered handle.

Run Builder with buffer if it can hold, write to device when buffer is full.

flushBuffer :: HasCallStack => BufferedOutput -> IO ()

Flush the buffer into output device(if buffer is not empty).

Exceptions

data IncompleteInput

Exceptions when read not enough input.

Note this exception is a sub-type of SomeIOException.

Constructors

IncompleteInput CallStack

Instances

Show IncompleteInput

Defined in Z.IO.Buffered

Methods

showsPrec :: Int -> IncompleteInput -> ShowS

show :: IncompleteInput -> String

showList :: [IncompleteInput] -> ShowS

Exception IncompleteInput

Defined in Z.IO.Buffered

Methods

toException :: IncompleteInput -> SomeException

fromException :: SomeException -> Maybe IncompleteInput

displayException :: IncompleteInput -> String

common buffer size

defaultChunkSize :: Int

The chunk size used for I/O. Currently set to 16k - chunkOverhead

smallChunkSize :: Int

The recommended chunk size. Currently set to 4k - chunkOverhead.

chunkOverhead :: Int

The memory management overhead. Currently this is tuned for GHC only.