Foreign.ForeignPtr.Unsafe

base-4.8.2.0: Basic libraries

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

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.