Data.ByteString.Builder.Extra

Copyright	(c) 2010 Jasper Van der Jeugt (c) 2010-2011 Simon Meier
License	BSD3-style (see LICENSE)
Maintainer	Simon Meier <iridcode@gmail.com>
Portability	GHC
Safe Haskell	Trustworthy
Language	Haskell98

Стратегии выполнения

toLazyByteStringWith Source

Интенсивное встраивание. Выполняет Builder с пользовательскими параметрами выполнения.

Эта функция встроена, несмотря на большой размер кода, чтобы позволить объединение со стратегией выделения. Например, функция выполнения по умолчанию Builder toLazyByteString определяется следующим образом.

{-# NOINLINE toLazyByteString #-}
toLazyByteString =
  toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) L.empty

где L.empty это ленивый ByteString нулевой длины.

В большинстве случаев параметры, используемые toLazyByteString, обеспечивают хорошую производительность. Неэффективный случай toLazyByteString - это выполнение коротких (<128 байт) Builders. В этом случае накладные расходы на выделение первого буфера размером 4 КБ и стоимость обрезки преобладают над стоимостью выполнения Builder. Вы можете избежать этой проблемы, используя

toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.empty

Это уменьшает накладные расходы на выделение и обрезку, так как все сгенерированные ByteStrings помещаются в первый буфер, и обрезка не требуется, если записано более 64 байт и менее 128 байт.

data AllocationStrategy Source

Стратегия выделения буфера для выполнения Builders.

safeStrategy Source

Используйте эту стратегию для генерации ленивых ByteStrings, чанки которых, вероятно, переживут одну сборку мусора. Эта стратегия обрезает буферы, заполненные менее чем наполовину, чтобы избежать чрезмерного расхода памяти.

untrimmedStrategy Source

Используйте эту стратегию для генерации ленивых ByteStrings, чанки которых удаляются сразу после их генерации. Например, если вы просто генерируете их для записи в сетевой сокет.

smallChunkSize :: Int Source

Рекомендуемый размер чанка. В настоящее время установлен в 4 КБ, за вычетом накладных расходов на управление памятью

defaultChunkSize :: Int Source

Размер чанка, используемый для ввода-вывода. В настоящее время установлен в 32 КБ, за вычетом накладных расходов на управление памятью

Управление границами чанков

byteStringCopy :: ByteString -> Builder Source

Создает Builder, который копирует строгий ByteString.

Используйте эту функцию для создания Builders из небольших (<= 4kb) ByteStrings или если вам нужно гарантировать, что ByteString не совместно используется с чанками, сгенерированными Builder.

byteStringInsert :: ByteString -> Builder Source

Создает Builder, который всегда вставляет строгий ByteString непосредственно как чанк.

Это подразумевает очистку выходного буфера, даже если он содержит всего один байт. Поэтому вы должны использовать byteStringInsert только для больших (> 8kb) ByteStrings. В противном случае сгенерированные чанки будут слишком фрагментированы для эффективной последующей обработки.

byteStringThreshold :: Int -> ByteString -> Builder Source

Создает Builder, который копирует строгие ByteStrings, если он меньше порога, и вставляет его напрямую в противном случае.

Например, byteStringThreshold 1024 копирует строгие ByteStrings, размер которых меньше или равен 1 КБ, и вставляет их напрямую в противном случае. Это означает, что средний размер чанка сгенерированного ленивого ByteString может быть всего 513 байт, так как между непосредственно вставленными 1025-байтовыми строгими ByteStrings всегда может быть всего один байт.

lazyByteStringCopy :: ByteString -> Builder Source

Создает Builder, который копирует ленивый ByteString.

lazyByteStringInsert :: ByteString -> Builder Source

Создает Builder, который вставляет все чанки ленивого ByteString напрямую.

lazyByteStringThreshold :: Int -> ByteString -> Builder Source

Создает Builder, который использует стратегию порогового значения byteStringThreshold для каждого чанка ленивого ByteString.

flush :: Builder Source

Очищает текущий буфер. Это создает границу чанка.

Низкоуровневое выполнение

type BufferWriter = Ptr Word8 -> Int -> IO (Int, Next) Source

BufferWriter представляет результат выполнения Builder. Он разворачивается как последовательность чанков данных. Эти чанки бывают двух видов:

• действие IO для записи данных Builder в предоставленный пользователем буфер памяти.
• существующие чанки данных, представленные строгим ByteString

Хотя это довольно низкий уровень, он предоставляет полную гибкость в том, как данные выводятся.

Сам BufferWriter является действием IO: вы предоставляете ему буфер (как указатель и длину), и он запишет данные в буфер. Он возвращает число, указывающее, сколько байтов фактически было записано (что может быть 0). Он также возвращает Next, который описывает, что будет дальше.

data Next Source

После выполнения действия BufferWriter существует три возможных варианта для того, что будет дальше:

runBuilder :: Builder -> BufferWriter Source

Преобразует Builder в его начальное действие BufferWriter.

Специфичные для хоста двоичные кодировки

intHost :: Int -> Builder Source

Кодирует целое число Int родной машины. Int кодируется в порядке и форме порядка байтов хоста для вашей машины. На 64-битной машине Int — это значение размером 8 байт, на 32-битной — 4 байта. Такие кодированные значения не будут переносимы на машины с другим порядком байтов или размером целых чисел без преобразования.

int16Host :: Int16 -> Builder Source

Кодирует Int16 в родном порядке и порядке байтов хоста.

int32Host :: Int32 -> Builder Source

Кодирует Int32 в родном порядке и порядке байтов хоста.

int64Host :: Int64 -> Builder Source

Кодирует Int64 в родном порядке и порядке байтов хоста.

wordHost :: Word -> Builder Source

Кодирует целое без знака Word родной машины. Word кодируется в порядке и форме порядка байтов хоста для вашей машины. На 64-битной машине Word — это значение размером 8 байт, на 32-битной — 4 байта. Такие кодированные значения не будут переносимы на машины с другим порядком байтов или размером целых чисел без преобразования.

word16Host :: Word16 -> Builder Source

Кодирует Word16 в родном порядке и порядке байтов хоста.

word32Host :: Word32 -> Builder Source

Кодирует Word32 в родном порядке и порядке байтов хоста.

word64Host :: Word64 -> Builder Source

Кодирует Word64 в родном порядке и порядке байтов хоста.

floatHost :: Float -> Builder Source

Кодирует Float в родном порядке. Такие кодированные значения не будут переносимы на машины с другим порядком байтов без преобразования.

doubleHost :: Double -> Builder Source

Кодирует Double в родном порядке.