Foreign.ForeignPtr

Авторские права	(c) Университет Глазго 2001
Лицензия	BSD-стиль (см. файл libraries/base/LICENSE)
Поддержка	ffi@haskell.org
Устойчивость	предварительная
Переносимость	переносимый
Безопасный Haskell	Надёжный
Язык	Haskell2010

Окончательные указатели на данные

data ForeignPtr a Источник

Тип ForeignPtr представляет ссылки на объекты, которые поддерживаются на языке внешнего вызова, то есть которые не являются частью структур данных, обычно управляемых менеджером памяти Haskell. Существенное различие между ForeignPtr и обычными ссылками на память типа Ptr a заключается в том, что первые могут быть связаны с финализаторами. Финализатор — это процедура, которая вызывается, когда менеджер памяти Haskell обнаруживает, что в куче и стеке Haskell больше нет ссылок, указывающих на ForeignPtr. Как правило, финализатор затем вызовет процедуры на языке внешнего вызова, которые освободят ресурсы, связанные с внешним объектом.

Тип ForeignPtr параметризован так же, как Ptr. Аргумент типа ForeignPtr обычно должен быть экземпляром класса Storable.

type FinalizerPtr a = FunPtr (Ptr a -> IO ()) Источник

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

Обратите внимание, что внешняя функция обязательно должна использовать соглашение вызова ccall.

type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ()) Источник

Основные операции

newForeignPtr :: FinalizerPtr a -> Ptr a -> IO (ForeignPtr a) Источник

Преобразует обычную ссылку на память в указатель на внешние данные и связывает с ссылкой финализатор. Финализатор будет выполнен после того, как последняя ссылка на внешний объект будет удалена. Однако нет гарантии оперативности, тем не менее, финализатор будет выполнен до завершения программы.

newForeignPtr_ :: Ptr a -> IO (ForeignPtr a) Источник

Преобразует обычную ссылку на память в указатель на внешние данные, которые могут быть связаны с финализаторами с помощью addForeignPtrFinalizer.

addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO () Источник

Эта функция добавляет финализатор к заданному внешнему объекту. Финализатор будет выполнен до всех других финализаторов для того же объекта, которые уже были зарегистрированы.

newForeignPtrEnv :: FinalizerEnvPtr env a -> Ptr env -> Ptr a -> IO (ForeignPtr a) Источник

Этот вариант newForeignPtr добавляет финализатор, который ожидает среду дополнительно к завершаемому указателю. Среда, которая будет передана финализатору, фиксируется вторым аргументом к newForeignPtrEnv.

addForeignPtrFinalizerEnv :: FinalizerEnvPtr env a -> Ptr env -> ForeignPtr a -> IO () Источник

Подобно addForeignPtrFinalizerEnv, но позволяет финализатору передавать дополнительный параметр среды, передаваемый финализатору. Среда, передаваемая финализатору, фиксируется вторым аргументом к addForeignPtrFinalizerEnv.

withForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b Источник

Это способ посмотреть на указатель, живущий внутри внешнего объекта. Эта функция принимает функцию, которая применяется к этому указателю. Результирующее действие IO затем выполняется. Внешний объект сохраняется живым по крайней мере во время всего действия, даже если он не используется напрямую внутри. Обратите внимание, что не безопасно возвращать указатель из действия и использовать его после завершения действия. Все использования указателя должны находиться внутри скобок withForeignPtr. Причина этой небезопасности такая же, как и для unsafeForeignPtrToPtr ниже: финализатор может быть выполнен раньше, чем ожидается, потому что компилятор может отслеживать только использование объекта ForeignPtr, а не объекта Ptr, созданного из него.

Эта функция обычно используется для преобразования данных к внешнему объекту или из него, используя операции из класса Storable.

finalizeForeignPtr :: ForeignPtr a -> IO () Источник

Вызывает немедленное выполнение финализаторов, связанных с указателем на внешние данные.

Операции низкого уровня

touchForeignPtr :: ForeignPtr a -> IO () Источник

Эта функция гарантирует, что внешний объект, о котором идёт речь, жив в данном месте последовательности действий IO. В частности, withForeignPtr выполняет touchForeignPtr после выполнения пользовательского действия.

Обратите внимание, что эту функцию не следует использовать для выражения зависимостей между финализаторами на ForeignPtr. Например, если финализатор для ForeignPtr F1 вызывает touchForeignPtr на втором ForeignPtr F2, то единственная гарантия заключается в том, что финализатор для F2 никогда не запускается до запуска финализатора для F1. Они могут быть запущены вместе, если, например, F1 и F2 в противном случае недостижимы, и в этом случае планировщик может запустить финализатор для F2 первым.

В общем случае не рекомендуется использовать финализаторы на отдельных объектах с ограничениями порядка между ними. Для выражения порядка надёжно требуются явные синхронизации с помощью MVar между финализаторами, но даже тогда среда выполнения иногда запускает несколько финализаторов последовательно в одном потоке (по соображениям производительности), поэтому синхронизация между финализаторами может привести к искусственному тупику. Другой альтернативой является использование явного подсчёта ссылок.

castForeignPtr :: ForeignPtr a -> ForeignPtr b Источник

Эта функция преобразует параметр ForeignPtr с одним типом в другой тип.

Выделение управляемой памяти

mallocForeignPtr :: Storable a => IO (ForeignPtr a) Source

Выделить некоторую память и вернуть к ней ForeignPtr. Память будет освобождена автоматически, когда ForeignPtr будет удалена.

mallocForeignPtr эквивалентно

   do { p <- malloc; newForeignPtr finalizerFree p }

хотя оно может быть реализовано по-другому внутри: вы не можете предполагать, что память, возвращенная mallocForeignPtr, была выделена с помощью malloc.

Замечания GHC: mallocForeignPtr имеет сильно оптимизированную реализацию в GHC. Она использует закреплённую память в куче сборки мусора, поэтому ForeignPtr не требует финализатора для освобождения памяти. Использование mallocForeignPtr и связанных функций настоятельно рекомендуется вместо newForeignPtr с финализатором.

mallocForeignPtrBytes :: Int -> IO (ForeignPtr a) Source

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

mallocForeignPtrArray :: Storable a => Int -> IO (ForeignPtr a) Source

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

mallocForeignPtrArray0 :: Storable a => Int -> IO (ForeignPtr a) Source

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