Foreign.StablePtr

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

Устойчивые ссылки на значения Haskell

data StablePtr a Источник

Устойчивая ссылка — это ссылка на выражение Haskell, которая гарантирует, что оно не будет затронуто сборкой мусора, т.е. не будет удалено и значение самой устойчивой ссылки не изменится во время сборки мусора (обычные ссылки могут быть перемещены во время сборки мусора). Следовательно, устойчивые ссылки могут быть переданы внешнему коду, который может рассматривать их как неявную ссылку на значение Haskell.

Значение типа StablePtr a — это устойчивая ссылка на выражение Haskell типа a.

newStablePtr :: a -> IO (StablePtr a) Source

Создать стабильную ссылку, ссылающуюся на данное значение Haskell.

deRefStablePtr :: StablePtr a -> IO a Source

Получить значение Haskell, на которое ссылается стабильная ссылка, т. е. то же значение, которое было передано соответствующему вызову newStablePtr. Если аргумент функции deRefStablePtr уже был освобождён с помощью freeStablePtr, поведение deRefStablePtr не определено.

freeStablePtr :: StablePtr a -> IO () Source

Разорвать связь между стабильной ссылкой и значением Haskell. После этого, если стабильная ссылка передается функции deRefStablePtr или freeStablePtr, поведение не определено. Однако стабильная ссылка все еще может быть передана функции castStablePtrToPtr, но значение Ptr (), возвращаемое функцией castStablePtrToPtr, в этом случае не определено (в частности, оно может быть nullPtr). Тем не менее, вызов castStablePtrToPtr гарантированно не будет циклическим.

castStablePtrToPtr :: StablePtr a -> Ptr () Source

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

castPtrToStablePtr :: Ptr () -> StablePtr a Source

Обратная функция к castStablePtrToPtr, т. е. у нас есть тождество

sp == castPtrToStablePtr (castStablePtrToPtr sp)

для любой стабильной ссылки sp, для которой freeStablePtr еще не выполнено. Кроме того, castPtrToStablePtr может применяться только к ссылкам, сгенерированным с помощью castStablePtrToPtr.

Интерфейс со стороны C

Следующее определение доступно C-программам, взаимодействующим с кодом Haskell, при включении заголовка HsFFI.h.

typedef void *HsStablePtr;  /* C representation of a StablePtr */

Обратите внимание, что нельзя делать никаких предположений о значениях, представляющих стабильные ссылки. В действительности, они даже не обязательно должны быть действительными адресами памяти. Единственная гарантия заключается в том, что если они будут возвращены в среду Haskell, функция deRefStablePtr сможет восстановить значение Haskell, на которое ссылается стабильная ссылка.