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	Safe
Language	Haskell2010

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

data StablePtr a Source

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

The StablePtr 0 is reserved for representing NULL in foreign code.

A value of type StablePtr a is a stable pointer to a Haskell expression of type 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, на которое указывает стабильный указатель.