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 ()) Исходный код

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

Обратите внимание, что внешняя функция должна использовать соглашение о вызове 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 () Исходный код

Подобно addForeignPtrFinalizer, но финализатор получает дополнительный параметр среды.

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

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

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

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

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

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

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 параметризованный одним типом в другой тип.

plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b Source

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

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

Since: base-4.10.0.0

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

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.