Foreign.ForeignPtr

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

Указатели на данные с финализаторами

data ForeignPtr a Источник

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

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

type FinalizerPtr a = FunPtr (Ptr a -> IO ()) Источник

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

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

type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ()) Источник

Основные операции

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

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

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

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

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

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

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

Этот вариант newForeignPtr добавляет финализатор, которому, помимо финализируемого указателя, требуется окружение. Окружение, передаваемое финализатору, задаётся вторым аргументом newForeignPtrEnv.

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

Аналогично addForeignPtrFinalizer, но финализатору передаётся дополнительный параметр окружения.

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

Эта функция позволяет получить доступ к указателю, хранящемуся во внешнем объекте. Она принимает функцию, которая применяется к этому указателю. Затем выполняется полученное действие IO. Внешний объект остаётся доступным как минимум на протяжении всего действия, даже если оно не использует его напрямую. Обратите внимание: небезопасно возвращать указатель из действия и использовать его после завершения действия. Все операции с указателем должны выполняться внутри скобок withForeignPtr. Причина этой небезопасности та же, что и у unsafeForeignPtrToPtr ниже: финализатор может запуститься раньше ожидаемого, поскольку компилятор может отслеживать использование только объекта ForeignPtr, но не объекта Ptr, созданного из него.

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

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

Немедленно запускает финализаторы, связанные с внешним указателем. После вызова этой функции внешний указатель нельзя использовать повторно. Если внешний указатель не поддерживает финализаторы, функция ничего не делает.

Низкоуровневые операции

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

Эта функция гарантирует, что соответствующий внешний объект будет доступен в указанном месте последовательности действий IO. Однако есть существенная оговорка: приведённая выше гарантия не действует, если GHC может доказать, что код перед touchForeignPtr не завершается (например, зацикливается или выбрасывает исключение). Поэтому настоятельно рекомендуется по возможности использовать вместо этого withForeignPtr.

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

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

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

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

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

Сдвигает указанный адрес на заданное смещение в байтах.

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

С версии: base-4.10.0.0

Выделение управляемой памяти

mallocForeignPtr :: Storable a => IO (ForeignPtr a) Источник

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

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

   do { p <- malloc; newForeignPtr finalizerFree p }

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

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

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

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

mallocForeignPtrArray :: Storable a => Int -> IO (ForeignPtr a) Источник

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

mallocForeignPtrArray0 :: Storable a => Int -> IO (ForeignPtr a) Source

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