unsafe -package -template-haskell
"Unsafe" IO operations.
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 Foreign.ForeignPtr.withForeignPtr rather than combinations of unsafeForeignPtrToPtr and touchForeignPtr. However, the latter routines are occasionally preferred in tool generated marshalling code.
unsafeInterleaveIO allows IO computation to be deferred lazily. When passed a value of type IO a, the IO will only be performed when the value of the a is demanded. This is used to implement lazy file reading, see System.IO.hGetContents.
Sometimes an external entity is a pure function, except that it passes arguments and/or results via pointers. The function unsafeLocalState permits the packaging of such entities as pure functions.
The only IO operations allowed in the IO action passed to unsafeLocalState are (a) local allocation (alloca, allocaBytes and derived operations such as withArray and withCString), and (b) pointer operations (Foreign.Storable and Foreign.Ptr) on the pointers to local storage, and (c) foreign functions whose only observable effect is to read and/or write the locally allocated memory. Passing an IO operation that does not obey these rules results in undefined behaviour.
It is expected that this operation will be replaced in a future revision of Haskell.
This is the "back door" into the IO monad, allowing IO computation to be performed at any time. For this to be safe, the IO computation should be free of side effects and independent of its environment.
If the I/O computation wrapped in unsafePerformIO performs side effects, then the relative order in which those side effects take place (relative to the main I/O trunk, or other calls to unsafePerformIO) is indeterminate. Furthermore, when using unsafePerformIO to cause side-effects, you should take the following precautions to ensure the side effects are performed as many times as you expect them to be. Note that these precautions are necessary for GHC, but may not be sufficient, and other compilers may require different precautions:
* Use {-# NOINLINE foo #-} as a pragma on any function foo that calls unsafePerformIO. If the call is inlined, the I/O may be performed more than once.
* Use the compiler flag -fno-cse to prevent common sub-expression elimination being performed on the module, which might combine two side effects that were meant to be separate. A good example is using multiple global variables (like test in the example below).
* Make sure that the either you switch off let-floating (-fno-full-laziness), or that the call to unsafePerformIO cannot float outside a lambda. For example, if you say: f x = unsafePerformIO (newIORef []) you may get only one reference cell shared between all calls to f. Better would be f x = unsafePerformIO (newIORef [x]) because now it can't float outside the lambda.
It is less well known that unsafePerformIO is not type safe. For example:
> test :: IORef [a]
> test = unsafePerformIO $ newIORef []
>
> main = do
> writeIORef test [42]
> bang <- readIORef test
> print (bang :: [Char])
This program will core dump. This problem with polymorphic references is well known in the ML community, and does not arise with normal monadic use of references. There is no easy way to make it impossible once you use unsafePerformIO. Indeed, it is possible to write coerce :: a -> b with the help of unsafePerformIO. So be careful!
Contains the various unsafe operations that can be performed on arrays.
A module containing unsafe ByteString operations.
While these functions have a stable API and you may use these functions in applications, do carefully consider the documented pre-conditions; incorrect use can break referential transparency or worse.
O(n) Copy a Text to an array. The array is assumed to be big enough to hold the contents of the entire Text.
A variety of drop which omits the checks on n so there is an obligation on the programmer to provide a proof that 0 <= n <= length xs.
Explicitly run the finaliser associated with a ByteString. References to this value after finalisation may generate invalid memory references.
This function is unsafe, as there may be other ByteStrings referring to the same underlying pages. If you use this, you need to have a proof of some kind that all ByteStrings ever generated from the underlying byte array are no longer live.
Construct a StorableArray from an arbitrary ForeignPtr. It is the caller's responsibility to ensure that the ForeignPtr points to an area of memory sufficient for the specified bounds.
Freeze a mutable array. Do not mutate the MArray afterwards!
Converts an mutable array into an immutable array. The implementation may either simply cast the array from one type to the other without copying the array, or it may take a full copy of the array.
Note that because the array is possibly not copied, any subsequent modifications made to the mutable version of the array may be shared with the immutable version. It is safe to use, therefore, if the mutable version is never modified after the freeze operation.
The non-copying implementation is supported between certain pairs of array types only; one constraint is that the array types must have identical representations. In GHC, The following pairs of array types have a non-copying O(1) implementation of unsafeFreeze. Because the optimised versions are enabled by specialisations, you will need to compile with optimisation (-O) to get them.
* IOUArray -> UArray
* STUArray -> UArray
* IOArray -> Array
* STArray -> Array
A variety of head for non-empty ByteStrings. unsafeHead omits the check for the empty case, so there is an obligation on the programmer to provide a proof that the ByteString is non-empty.
Unchecked read of an immutable array. May return garbage or crash on an out-of-bounds access.
Unsafe ByteString index (subscript) operator, starting from 0, returning a Word8 This omits the bounds check, which means there is an accompanying obligation on the programmer to ensure the bounds are checked in some other way.
Show more results