Foreign.ForeignPtr.Safe

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 (Указатель a -> IO ()) Исходный код

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

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

type FinalizerEnvPtr env a = FunPtr (Указатель env -> Указатель a -> IO ()) Исходный код

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

newForeignPtr :: FinalizerPtr a -> Указатель a -> IO (ForeignPtr a) Исходный код

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

newForeignPtr_ :: Указатель a -> IO (ForeignPtr a) Исходный код

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

addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO () Исходный код

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

newForeignPtrEnv :: FinalizerEnvPtr env a -> Указатель env -> Указатель a -> IO (ForeignPtr a) Исходный код

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

addForeignPtrFinalizerEnv :: FinalizerEnvPtr env a -> Указатель env -> ForeignPtr a -> IO () Исходный код

Как addForeignPtrFinalizer, но финализатору передается дополнительный параметр среды.

withForeignPtr :: ForeignPtr a -> (Указатель a -> IO b) -> IO b Исходный код

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

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

finalizeForeignPtr :: ForeignPtr a -> IO () Source

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

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

touchForeignPtr :: ForeignPtr a -> IO () Source

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

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

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

castForeignPtr :: ForeignPtr a -> ForeignPtr b Source

Эта функция преобразует параметризованный 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.