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	Safe
Language	Haskell2010

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

data ForeignPtr a Source

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

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

type FinalizerPtr a = Функция-указатель (Указатель a -> IO ()) Исходный код

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

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

type FinalizerEnvPtr env a = Функция-указатель (Указатель 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 () Исходный код

Принудительно вызывает финализаторы, связанные с указателем на внешние данные. После вызова этой функции указатель на внешние данные больше нельзя использовать. Если указатель на внешние данные не поддерживает финализаторы, это является пустой операцией.

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

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

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

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

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

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

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

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

Перемещает указанный адрес на заданный смещение в байтах.

Новый ForeignPtr разделяет финализатор исходного, что с точки зрения финализации эквивалентно простому созданию ещё одной ссылки на исходный. То есть, финализатор не будет вызван до тех пор, пока новый ForeignPtr не станет недоступным, а также не будет вызван дополнительный раз из-за этого вызова; финализатор будет вызван с тем же адресом, что и без этого вызова, а *не* с новым.

С версии: base-4.10.0.0

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

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.