Foreign.StablePtr

Авторские права	(c) The University of Glasgow 2001
Лицензия	в стиле BSD (см. файл libraries/base/LICENSE)
Сопровождающий	ffi@haskell.org
Стабильность	предварительная
Переносимость	переносимый
Безопасный Haskell	Безопасный
Язык	Haskell2010

Стабильные ссылки на значения Haskell

data StablePtr a Источник

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

StablePtr 0 зарезервировано для представления NULL во внешнем коде.

Значение типа StablePtr a является стабильным указателем на выражение Haskell типа a.

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

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

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

Получает значение Haskell, на которое ссылается стабильный указатель, то есть то же значение, которое было передано в соответствующий вызов newStablePtr. Если аргумент 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, на которое ссылается стабильный указатель.