Foreign.ForeignPtr.Безопасный

Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	ffi@haskell.org
Stability	provisional
Portability	portable
Safe Haskell	Trustworthy
Language	Haskell2010

Финализированные указатели на данные

data ForeignPtr a Source

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

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

type FinalizerPtr a = FunPtr (Ptr a -> IO ()) Source

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

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

type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ()) Source

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

newForeignPtr :: FinalizerPtr a -> Ptr a -> IO (ForeignPtr a) Source

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

newForeignPtr_ :: Ptr a -> IO (ForeignPtr a) Source

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

addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO () Source

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

newForeignPtrEnv :: FinalizerEnvPtr env a -> Ptr env -> Ptr a -> IO (ForeignPtr a) Source

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

addForeignPtrFinalizerEnv :: FinalizerEnvPtr env a -> Ptr env -> ForeignPtr a -> IO () Source

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

withForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b Source

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

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

finalizeForeignPtr :: ForeignPtr a -> IO () Source

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

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

touchForeignPtr :: ForeignPtr a -> IO () Source

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

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

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

castForeignPtr :: ForeignPtr a -> ForeignPtr b Source

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

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

mallocForeignPtr :: Storable a => IO (ForeignPtr a) Источник

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

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

   do { p <- malloc; newForeignPtr finalizerFree p }

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

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

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

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

mallocForeignPtrArray :: Storable a => Int -> IO (ForeignPtr a) Источник

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

mallocForeignPtrArray0 :: Storable a => Int -> IO (ForeignPtr a) Источник

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