base-4.5.1.0: Basic libraries

Portability | portable
Stability | provisional
Maintainer | ffi@haskell.org
Safe Haskell | Unsafe

Foreign.ForeignPtr.Unsafe

Contents

- Unsafe low-level operations

Description

The `ForeignPtr` type and operations. This module is part of the Foreign Function Interface (FFI) and will usually be imported via the Foreign module.

Unsafe API Only.

Synopsis

- unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a

## Unsafe low-level operations

unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a

This function extracts the pointer component of a foreign pointer. This is a potentially dangerous operations, as if the argument to `unsafeForeignPtrToPtr` is the last usage occurrence of the given foreign pointer, then its finalizer(s) will be run, which potentially invalidates the plain pointer just obtained. Hence, `touchForeignPtr` must be used wherever it has to be guaranteed that the pointer lives on - i.e., has another usage occurrence.

To avoid subtle coding errors, hand written marshalling code should preferably use `withForeignPtr` rather than combinations of `unsafeForeignPtrToPtr` and `touchForeignPtr`. However, the latter routines are occasionally preferred in tool generated marshalling code.