Главная » Haskell » Модуль ForeignPtr

0

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

import  Foreign.ForeignPtr

Главный тип данных, описанный в этом модуле, — ForeignPtr. Все остальные программные сущности предназначены для обслуживания этого типа.

Тип: ForeignPtr

Описание: данный тип представляет ссылку на объект, который создан при помощи стороннего языка программирования, то есть на объект, который не входит в систему структур данных, обслуживаемые менеджером памяти языка Haskell. Главное отличие этого типа от простых ссылок на память посредством типа Ptr  заключается в том, что рассматриваемый тип позволяет ассоциировать со своими значениями финализаторы. Под финализатором (иначе — деструктором) понимается функция, запускаемая тогда, когда сборщик мусора языка Haskell обнаруживает, что на внешний объект больше не существует ссылок из сегмента памяти, который  обслуживается сборщиком мусора. Обычно  финализатор при запуске в свою очередь запускает деструкторы из стороннего языка программирования, которые освобождают память.

Определение:

data  ForeignPtr  a  = …

Тип определён в виде примитива.

Для этого типа определены экземпляры следующих классов: Typeaple1, Data,

Eq, Ord и Show.

Для удобства работы с финализваторами  определено два  дополнительных синонима.

Тип: FinalizerPtr

Описание: финализатор представляется в виде указателя на функцию, которая получает на вход обычный указатель на значение, которое должно быть уничтожено.

Определение:

type  FinalizerPtr a = FunPtr  (Ptr  a ->  IO ())

Тип: FinalizerEnvPtr

Описание: вариант типа FinalizerPtr, в котором финализатор является функцией, получающей на вход не только уничтожаемое  значение, но и состояние окружения.

Определение:

type  FinalizerEnvPtr env a = FunPtr  (Ptr env ->  Ptr  a ->  IO ())

Функция: newForeignPtr

Описание: преобразует обычный указатель в указатель на внешний объект, ассоциируя с указателем заданный финализатор. Этот финализатор будет выполнен, как только пропадёт последняя ссылка на внешний объект. Необходимо отметить, что неизвестно, как скоро будет запущен финализатор, это зависит от настроек сборщика мусора языка Haskell. Единственной гарантией является то, что финализатор будет запущен в любом случае перед окончанием работы программы. Определение:

newForeignPtr   :: FinalizerPtr a ->  Ptr   a ->  IO  (ForeignPtr a) newForeignPtr   finalizer p = do fObj  < newForeignPtr_  p

addForeignPtrFinalizer  finalizer fObj  return fObj

Функция: newForeignPtr-

Описание: вариант функции newForeignPtr,  который не ассоциирует финализатор с внешним указателем. Финализатор может быть добавлен позже при помощи функции addForeignPtrFinalizer.

Определение:

newForeignPtr_  :: Ptr   a ->  IO  (ForeignPtr a)

Функция определена в виде примитива.

Функция: addForeignPtrFinalizer

Описание: ассоциирует с указателем на внешний объект заданный финализатор. К каждому внешнему объекту можно приписать несколько финализаторов, которые будут выполняться в порядке FILO (последний ассоциированный указатель выполнится первым).

Определение:

addForeignPtrFinalizer :: FinalizerPtr a ->  ForeignPtr a  ->  IO ()

Функция определена в виде примитива.

Функция: newForeignPtrEnv

Описание: вариант функции newForeignPtr,  который  ассоциирует  с  внешним объектом финализатор, ожидающий на вход не только ссылку на объект, но и состояние окружения.

Определение:

newForeignPtrEnv  :: FinalizerEnvPtr env a ->  Ptr   env ->  Ptr   a ->  IO  (ForeignPtr a) newForeignPtrEnv  finalizer env p = do fObj  < newForeignPtr_  p

addForeignPtrFinalizerEnv finalizer  env fObj  return fObj

Функция: addForeignPtrFinalizerEnv

Описание:  вариант  функции   addForeignPtrFinalizer,  который   добавляет к внешнему объекту финализатор, ожидающий на вход не только ссылку на объект, но и состояние окружения.

Определение:

addForeignPtrFinalizerEnv :: FinalizerEnvPtr env a ->  Ptr   env ->  ForeignPtr a  ->  IO ()

Функция определена в виде примитива.

Функция: withForeignPtr

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

Определение:

withForeignPtr :: ForeignPtr a ->  (Ptr a ->  IO  b)  ->  IO b withForeignPtr fo io  = do r < io  (unsafeForeignPtrToPtr fo)

touchForeignPtr  fo return  r

Функция: finalizeForeignPtr

Описание: заставляет немедленно запустить финализатор, ассоциированный с заданным внешним объектом.

Определение:

finalizeForeignPtr ::  ForeignPtr  a ->  IO ()

Функция определена в виде примитива.

Функция: unsafeForeignPtrToPtr

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

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

Определение:

unsafeForeignPtrToPtr :: ForeignPtr a ->  Ptr   a

Функция определена в виде примитива.

Функция: touchForeignPtr

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

touchForeignPtr :: ForeignPtr a ->  IO ()

Функция определена в виде примитива.

Функция: castForeignPtr

Описание: преобразует указатель на внешний объект в смысле изменения параметризуемого типа.

Определение:

castForeignPtr :: ForeignPtr a ->  ForeignPtr b

Функция определена в виде примитива.

Функция: mallocForeignPtr

Описание: выделяет некоторое количество памяти и возвращает указатель на неё.

Определение:

mallocForeignPtr :: Storable a => IO  (ForeignPtr a) mallocForeignPtr = do r < malloc

newForeignPtr   finalizerFree r

Функция: mallocForeignPtrBytes

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

Определение:

mallocForeignPtrBytes :: Int ->  IO  (ForeignPtr a) mallocForeignPtrBytes n  = do r < mallocBytes n

newForeignPtr  finalizerFree r

Функция: mallocForeignPtrArray

Описание: вариант функции mallocArray (см. стр. 447), снабжающий выделяемую область памяти ассоциированным с ней финализатором.

Определение:

mallocForeignPtrArray :: Storable a => Int ->  IO  (ForeignPtr a) mallocForeignPtrArray = doMalloc  undefined

where

doMalloc                       :: Storable b => b ->  Int ->  IO  (ForeignPtr b) doMalloc  dummy  size =  mallocForeignPtrBytes (size  * sizeOf dummy)

Функция: mallocForeignPtrArray0

Описание: вариант функции mallocArray0 (см. стр. 448), снабжающий выделяемую область памяти ассоциированным с ней финализатором.

Определение:

mallocForeignPtrArray0 :: Storable a => Int ->  IO  (ForeignPtr a) mallocForeignPtrArray0 size  =  mallocForeignPtrArray (size  + 1)

Источник: Душкин Р. В., Справочник по языку Haskell. М.: ДМК Пресс, 2008. 544 с., ил.

По теме:

  • Комментарии