GHC.ForeignPtr

Авторские права	(c) Университет Глазго 1992-2003
Лицензия	см. libraries/base/LICENSE
Поддержка	cvs-ghc@haskell.org
Устойчивость	внутренняя
Переносимость	непереносимая (расширения GHC)
Безопасный Haskell	Небезопасный
Язык	Haskell2010

data ForeignPtr a Исходный код

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

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

data ForeignPtrContents Исходный код

data Finalizers Исходный код

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

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

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

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

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

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

mallocForeignPtr :: Storable a => IO (ForeignPtr a) Исходный код

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

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

   do { p <- malloc; newForeignPtr finalizerFree p }

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

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

mallocPlainForeignPtr :: Storable a => IO (ForeignPtr a) Исходный код

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

Примечания GHC: mallocPlainForeignPtr имеет сильно оптимизированную реализацию в GHC. Он использует закреплённую память в куче с автоматическим сбором мусора, как и mallocForeignPtr. В отличие от mallocForeignPtr, ForeignPtr, созданный с помощью mallocPlainForeignPtr, не несёт финализаторов. Добавить финализатор к ForeignPtr, созданному таким образом, или завершить работу такого указателя невозможно. Это полезно для ForeignPtr, которые будут существовать только внутри Haskell (например, для созданных упакованных строк). Попытки добавить финализатор к ForeignPtr, созданному таким образом, или завершить работу такого указателя приведут к исключению.

mallocForeignPtrBytes :: Целое -> IO (ForeignPtr a) Исходный код

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

mallocPlainForeignPtrBytes :: Целое -> IO (ForeignPtr a) Исходный код

Эта функция похожа на mallocForeignPtrBytes, за исключением того, что внутренне используется оптимизированное представление ForeignPtr без финализатора. Попытки добавить финализатор приведут к исключению.

mallocForeignPtrAlignedBytes :: Целое -> Целое -> IO (ForeignPtr a) Исходный код

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

mallocPlainForeignPtrAlignedBytes :: Целое -> Целое -> IO (ForeignPtr a) Исходный код

Эта функция похожа на mallocForeignPtrAlignedBytes, за исключением того, что внутренне используется оптимизированное представление ForeignPtr без финализатора. Попытки добавить финализатор приведут к исключению.

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

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

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

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

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

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

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

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

unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a Источник

Эта функция извлекает компонент указателя внешнего указателя. Это потенциально опасная операция, так как если аргумент unsafeForeignPtrToPtr является последним использованием данного внешнего указателя, то его финализатор(ы) будет запущен(ы), что потенциально делает недействительным просто полученный указатель. Следовательно, touchForeignPtr должен использоваться всякий раз, когда необходимо гарантировать существование указателя — т.е. когда существует ещё одно использование.

Чтобы избежать тонких ошибок в кодировании, написанный вручную код маппинга предпочтительно использует withForeignPtr вместо комбинаций unsafeForeignPtrToPtr и touchForeignPtr. Однако, последние процедуры иногда предпочтительнее в инструментом генерируемом коде маппинга.

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

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

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

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

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

С версии: base-4.10.0.0

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

Преобразует обычную ссылку на память во внешний объект, связав финализатор — заданный моноидной операцией — со ссылкой. Управляющий хранилищем запустит финализатор в отдельном потоке в какой-то момент после того, как последняя ссылка на ForeignPtr будет удалена. Нет гарантии оперативности, и, на самом деле, нет гарантии, что финализатор вообще когда-нибудь выполнится.

Обратите внимание, что ссылки из финализатора не обязательно предотвращают завершение работы другого объекта. Если финализатор A ссылается на B (возможно, используя touchForeignPtr, то единственной гарантией является то, что финализатор B никогда не начнется до финализатора A. Если A и B недоступны, то оба финализатора начнутся одновременно. Смотрите touchForeignPtr для получения более подробной информации о порядке финализаторов.

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

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

Это вариант addForeignPtrFinalizer, где финализатор — это произвольное IO действие. Когда он вызывается, финализатор выполняется в новом потоке.

Примечание. Будьте очень осторожны с этими финализаторами. Частая ошибка заключается в том, что если финализатор ссылается на другой завершённый объект, он не предотвращает завершения работы этого объекта. В частности, Handle являются объектами, которые завершают работу, поэтому финализатор не должен ссылаться на Handle (включая stdout, stdin, или stderr).

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

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