Z-IO-0.2.0.0: Simple and high performance IO toolkit for Haskell
Copyright(c) Dong Han 2017-2020
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Z.IO.Buffered

Description

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.

Synopsis

Input & Output device

class Input i where Source #

Input device

readInput should return 0 on EOF.

Methods

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

Instances

Instances details
Input StdStream Source # 
Instance details

Defined in Z.IO.StdStream

Input FilePtrT Source # 
Instance details

Defined in Z.IO.FileSystem.Threaded

Methods

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

Input File Source # 
Instance details

Defined in Z.IO.FileSystem.Threaded

Methods

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

Input FilePtr Source # 
Instance details

Defined in Z.IO.FileSystem

Methods

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

Input File Source # 
Instance details

Defined in Z.IO.FileSystem

Methods

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

Input UVStream Source # 
Instance details

Defined in Z.IO.UV.UVStream

Methods

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

class Output o where Source #

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 () Source #

Instances

Instances details
Output StdStream Source # 
Instance details

Defined in Z.IO.StdStream

Methods

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

Output FilePtrT Source # 
Instance details

Defined in Z.IO.FileSystem.Threaded

Methods

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

Output File Source # 
Instance details

Defined in Z.IO.FileSystem.Threaded

Methods

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

Output FilePtr Source # 
Instance details

Defined in Z.IO.FileSystem

Methods

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

Output File Source # 
Instance details

Defined in Z.IO.FileSystem

Methods

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

Output UVStream Source # 
Instance details

Defined in Z.IO.UV.UVStream

Methods

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

Buffered Input

data BufferedInput Source #

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.

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

Open a new buffered input with defaultChunkSize as buffer size.

newBufferedInput' Source #

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 Source #

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 Source #

Request UTF8 Text chunk from BufferedInput.

The buffer size must be larger than 4 bytes to guarantee decoding progress. If there're trailing bytes before EOF, IncompleteInput are thrown.

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

Push bytes back into buffer(if not empty).

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

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 Source #

Read exactly N bytes.

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

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

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

Empty bytes indicate EOF. if EOF is reached before meet a magic byte, partial bytes are returned.

 /----- readToMagic ----- \ /----- readToMagic -----\ ...
+------------------+-------+-----------------+-------+
|       ...        | magic |       ...       | magic | ...
+------------------+-------+-----------------+-------+

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

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 ---\ discarded /--- readLine ---\ discarded / ...
+------------------+---------+------------------+---------+
|      ...         | \r\n/\n |       ...        | \r\n/\n | ...
+------------------+---------+------------------+---------+

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

Read all chunks from a BufferedInput until EOF.

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

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

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 Source #

Output device with buffer, NOT THREAD SAFE!

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

Open a new buffered output with defaultChunkSize as buffer size.

newBufferedOutput' Source #

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 () Source #

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 () Source #

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 () Source #

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

Exceptions

data IncompleteInput Source #

Exceptions when read not enough input.

Note this exception is a sub-type of SomeIOException.

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.