diff options
| author | Andreas Klebinger <klebinger.andreas@gmx.at> | 2022-02-02 15:18:42 +0100 |
|---|---|---|
| committer | Andreas Klebinger <klebinger.andreas@gmx.at> | 2022-02-09 15:20:12 +0000 |
| commit | 36db87c3ed3319a9055a0327033506532dbdf29e (patch) | |
| tree | 6dc5d265c9c5a1d48200f0a42772a1da8d891ce6 | |
| parent | 1dbe5b2a97c41b3f24a48372ba25faeae08e8cd6 (diff) | |
| download | haskell-wip/andreask/T21025.tar.gz | |
Docs:Mention that safe calls don't keep their arguments alive.wip/andreask/T21025
| -rw-r--r-- | docs/users_guide/exts/ffi.rst | 11 |
1 files changed, 9 insertions, 2 deletions
diff --git a/docs/users_guide/exts/ffi.rst b/docs/users_guide/exts/ffi.rst index 2419fadf01..6d96a0216a 100644 --- a/docs/users_guide/exts/ffi.rst +++ b/docs/users_guide/exts/ffi.rst @@ -139,6 +139,11 @@ restrictions: Since the runtime has no facilities for tracking mutation of a ``MutableByteArray#``, these can be safely mutated in any foreign function. +* Note that ``safe`` FFI calls don't take any measures to keep their + arguments alive while the called C function runs. For arguments + who's live time doesn't extend past the FFI call ``keepAlive#`` or a + ``StablePtr`` should be used to ensure the argument isn't garbage + collected before the call finishes. None of these restrictions are enforced at compile time. Failure to heed these restrictions will lead to runtime errors that can be @@ -1094,8 +1099,10 @@ Pinned Byte Arrays A pinned byte array is one that the garbage collector is not allowed to move. Consequently, it has a stable address that can be safely -requested with ``byteArrayContents#``. There are a handful of -primitive functions in :ghc-prim-ref:`GHC.Prim.` +requested with ``byteArrayContents#``. Not that being pinned doesn't +prevent the byteArray from being gc'ed in the same fashion a regular +byte array would be. +There are a handful of primitive functions in :ghc-prim-ref:`GHC.Prim.` used to enforce or check for pinnedness: ``isByteArrayPinned#``, ``isMutableByteArrayPinned#``, and ``newPinnedByteArray#``. A byte array can be pinned as a result of three possible causes: |