Foreign.StablePtr

Авторские права	(c) Университет Глазго 2001
Лицензия	BSD-стиль (см. файл libraries/base/LICENSE)
Поддержка	ffi@haskell.org
Устойчивость	предварительная
Переносимость	переносимая
Безопасный Haskell	Надежный
Язык	Haskell2010

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

data StablePtr a Источник

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

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

newStablePtr :: a -> IO (StablePtr a) Источник

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

deRefStablePtr :: StablePtr a -> IO a Источник

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

freeStablePtr :: StablePtr a -> IO () Источник

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

castStablePtrToPtr :: StablePtr a -> Ptr () Источник

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

castPtrToStablePtr :: Ptr () -> StablePtr a Источник

Обратное преобразование функции 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, на которое ссылается устойчивый указатель.