Foreign.Storable
| Авторское право | (c) The FFI task force 2001 |
|---|---|
| Лицензия | см. libraries/base/LICENSE |
| Сопровождающий | ffi@haskell.org |
| Стабильность | предварительная |
| Переносимость | переносимая |
| Безопасный Haskell | Safe |
| Язык | Haskell2010 |
Описание
Модуль Foreign.Storable предоставляет наиболее базовые средства для маршалинга и является частью независимой от языка части Foreign Function Interface (FFI); обычно он импортируется через модуль Foreign.
class Storable a where Источник
Функции-члены этого класса упрощают запись значений примитивных типов в необработанную память (которая могла быть выделена с помощью упомянутых выше процедур) и чтение значений из областей необработанной памяти. Кроме того, класс позволяет вычислять требования к объёму памяти и ограничения выравнивания для сохраняемых типов.
Адреса памяти представлены значениями типа Ptr a для некоторого a, являющегося экземпляром класса Storable. Аргумент типа для Ptr помогает обеспечить полезную типобезопасность в коде FFI (нельзя смешивать указатели разных типов без явного приведения), а также помогает системе типов Haskell определить, какой метод маршалинга нужен для заданного указателя.
Весь маршалинг между Haskell и внешним языком в конечном счёте сводится к преобразованию структур данных Haskell в двоичное представление соответствующей структуры данных внешнего языка и обратно. Чтобы реализовать этот маршалинг на Haskell, необходимо работать с примитивными типами данных, хранящимися в неструктурированных блоках памяти. Класс Storable упрощает работу со всеми типами, для которых он реализован: стандартными базовыми типами Haskell, типами Int фиксированного размера (Int8, Int16, Int32, Int64), типами Word фиксированного размера (Word8, Word16, Word32, Word64), StablePtr, всеми типами из Foreign.C.Types, а также Ptr.
Минимальное полное определение
sizeOf, alignment, (peek | peekElemOff | peekByteOff), (poke | pokeElemOff | pokeByteOff)
Методы
Вычисляет требования к объёму памяти (в байтах) для аргумента. Значение аргумента не используется.
alignment :: a -> Int Источник
Вычисляет ограничение выравнивания для аргумента. Ограничение выравнивания x выполняется для любого адреса, делящегося на x без остатка. Если этот экземпляр используется с alloca или allocaArray, выравнивание должно быть степенью двойки. Значение аргумента не используется.
peekElemOff :: Ptr a -> Int -> IO a Источник
Читает значение из области памяти, рассматриваемой как массив однотипных значений. Первый аргумент задаёт начальный адрес массива, а второй — индекс в массиве (индекс первого элемента массива равен 0). Выполняется следующее равенство:
peekElemOff addr idx = IOExts.fixIO $ \result -> peek (addr `plusPtr` (idx * sizeOf result))
Обратите внимание: это лишь спецификация, а не обязательно фактическая реализация функции.
pokeElemOff :: Ptr a -> Int -> a -> IO () Источник
Записывает значение в область памяти, рассматриваемую как массив однотипных значений. Выполняется следующее равенство:
pokeElemOff addr idx x = poke (addr `plusPtr` (idx * sizeOf x)) x
peekByteOff :: Ptr b -> Int -> IO a Источник
Читает значение из ячейки памяти, заданной базовым адресом и смещением. Выполняется следующее равенство:
peekByteOff addr off = peek (addr `plusPtr` off)
pokeByteOff :: Ptr b -> Int -> a -> IO () Источник
Записывает значение в ячейку памяти, заданную базовым адресом и смещением. Выполняется следующее равенство:
pokeByteOff addr off x = poke (addr `plusPtr` off) x
peek :: Ptr a -> IO a Источник
Читает значение из заданной ячейки памяти.
Обратите внимание, что для корректной работы функций peek и poke могут потребоваться правильно выровненные адреса. Это зависит от архитектуры; поэтому переносимый код должен обеспечивать выполнение ограничения выравнивания для a, заданного функцией alignment, при чтении или записи значений типа a.
poke :: Ptr a -> a -> IO () Источник
Записывает заданное значение в указанную ячейку памяти. Могут применяться ограничения выравнивания; см. peek.
Экземпляры
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/9.14.1/docs/libraries/base-4.22.0.0-66f8/Foreign-Storable.html