diff options
| author | Andrew Martin <andrew.thaddeus@gmail.com> | 2019-07-19 08:41:27 -0400 |
|---|---|---|
| committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2019-10-08 13:24:52 -0400 |
| commit | 6a5c249d54d542d765ddbd80161ef4796c781de1 (patch) | |
| tree | a44a8f7a5b259270bf3a30b5f435b7f4ba2b659d | |
| parent | 0c7a5bcd9c01dd4b8ced5096c8ba2705db3409af (diff) | |
| download | haskell-6a5c249d54d542d765ddbd80161ef4796c781de1.tar.gz | |
[skip ci] clarify what unsound means
| -rw-r--r-- | docs/users_guide/ffi-chap.rst | 42 |
1 files changed, 24 insertions, 18 deletions
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst index 3d1dc9c680..fb001a5b83 100644 --- a/docs/users_guide/ffi-chap.rst +++ b/docs/users_guide/ffi-chap.rst @@ -111,24 +111,30 @@ very difficult to track down. (The errors likely will not manifest until garbage collection happens.) In tabular form, these restrictions are: -+--------------------------------+-----------------------------------------------------+ -| | When value is used as argument to FFI call that is | -+--------------------------------+-------------------------+---------------------------+ -| | ``foreign import safe`` | ``foreign import unsafe`` | -+--------------------------------+-----------+-------------+-----------+---------------+ -| Argument Type | reads are | writes are | reads are | writes are | -+--------------------------------+-----------+-------------+-----------+---------------+ -| ``Array#`` | Unsound | Unsound | Sound | Unsound | -| ``MutableArray#`` | Unsound | Unsound | Sound | Unsound | -| ``SmallArray#`` | Unsound | Unsound | Sound | Unsound | -| ``MutableSmallArray#`` | Unsound | Unsound | Sound | Unsound | -| ``ArrayArray#`` | Unsound | Unsound | Sound | Unsound | -| ``MutableArrayArray#`` | Unsound | Unsound | Sound | Unsound | -| unpinned ``ByteArray#`` | Unsound | Unsound | Sound | Unsound | -| unpinned ``MutableByteArray#`` | Unsound | Unsound | Sound | Sound | -| pinned ``ByteArray#`` | Sound | Unsound | Sound | Unsound | -| pinned ``MutableByteArray#`` | Sound | Sound | Sound | Sound | -+--------------------------------+-----------+-------------+-----------+---------------+ +.. table:: Restrictions on unlifted boxed arguments passed to foreign C calls. + Cells marked as "Unsound" represent combinations that lead to + undefined runtime behavior. GHC does not reject such unsound + programs at compile time. + :widths: auto + + +--------------------------------+-----------------------------------------------------+ + | | When value is used as argument to FFI call that is | + +--------------------------------+-------------------------+---------------------------+ + | | ``foreign import safe`` | ``foreign import unsafe`` | + +--------------------------------+-----------+-------------+-----------+---------------+ + | Argument Type | reads are | writes are | reads are | writes are | + +================================+===========+=============+===========+===============+ + | ``Array#`` | Unsound | Unsound | Sound | Unsound | + | ``MutableArray#`` | Unsound | Unsound | Sound | Unsound | + | ``SmallArray#`` | Unsound | Unsound | Sound | Unsound | + | ``MutableSmallArray#`` | Unsound | Unsound | Sound | Unsound | + | ``ArrayArray#`` | Unsound | Unsound | Sound | Unsound | + | ``MutableArrayArray#`` | Unsound | Unsound | Sound | Unsound | + | unpinned ``ByteArray#`` | Unsound | Unsound | Sound | Unsound | + | unpinned ``MutableByteArray#`` | Unsound | Unsound | Sound | Sound | + | pinned ``ByteArray#`` | Sound | Unsound | Sound | Unsound | + | pinned ``MutableByteArray#`` | Sound | Sound | Sound | Sound | + +--------------------------------+-----------+-------------+-----------+---------------+ When passing any of the unlifted array types as an argument to a foreign C call, a foreign function sees a pointer that refers to the |