for package:base-prelude

for is traverse with its arguments flipped. For a version that ignores the results see for_.

forM is mapM with its arguments flipped. For a version that ignores the results see forM_.

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see forM. forM_ is just like for_, but specialised to monadic actions.

for_ is traverse_ with its arguments flipped. For a version that doesn't ignore the results see for. This is forM_ generalised to Applicative actions. for_ is just like forM_, but generalised to Applicative actions.

Examples

Basic usage:

>>> for_ [1..4] print
1
2
3
4

Repeat an action indefinitely.

Examples

A common use of forever is to process input from network sockets, Handles, and channels (e.g. MVar and Chan). For example, here is how we might implement an echo server, using forever both to listen for client connections on a network socket and to echo client input on client connection handles:

echoServer :: Socket -> IO ()
echoServer socket = forever $ do
client <- accept socket
forkFinally (echo client) (\_ -> hClose client)
where
echo :: Handle -> IO ()
echo client = forever $
hGetLine client >>= hPutStrLn client

Note that "forever" isn't necessarily non-terminating. If the action is in a MonadPlus and short-circuits after some number of iterations. then forever actually returns mzero, effectively short-circuiting its caller.

Fork a thread and call the supplied function when the thread is about to terminate, with an exception or a returned value. The function is called with asynchronous exceptions masked.

forkFinally action and_then =
mask $ \restore ->
forkIO $ try (restore action) >>= and_then

This function is useful for informing the parent when a child terminates, for example.

Creates a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread. The new thread will be a lightweight, unbound thread. Foreign calls made by this thread are not guaranteed to be made by any particular OS thread; if you need foreign calls to be made by a particular OS thread, then use forkOS instead. The new thread inherits the masked state of the parent (see mask). The newly created thread has an exception handler that discards the exceptions BlockedIndefinitelyOnMVar, BlockedIndefinitelyOnSTM, and ThreadKilled, and passes all other exceptions to the uncaught exception handler.

Like forkIO, but the child thread is passed a function that can be used to unmask asynchronous exceptions. This function is typically used in the following way

... mask_ $ forkIOWithUnmask $ \unmask ->
catch (unmask ...) handler

so that the exception handler in the child thread is established with asynchronous exceptions masked, meanwhile the main body of the child thread is executed in the unmasked state. Note that the unmask function passed to the child thread should only be used in that thread; the behaviour is undefined if it is invoked in a different thread.

Like forkIO, this sparks off a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread. However, forkOS creates a bound thread, which is necessary if you need to call foreign (non-Haskell) libraries that make use of thread-local state, such as OpenGL (see Control.Concurrent#boundthreads). Using forkOS instead of forkIO makes no difference at all to the scheduling behaviour of the Haskell runtime system. It is a common misconception that you need to use forkOS instead of forkIO to avoid blocking all the Haskell threads when making a foreign call; this isn't the case. To allow foreign calls to be made without blocking all the Haskell threads (with GHC), it is only necessary to use the -threaded option when linking your program, and to make sure the foreign import is not marked unsafe.

Like forkIOWithUnmask, but the child thread is a bound thread, as with forkOS.

Like forkIO, but lets you specify on which capability the thread should run. Unlike a forkIO thread, a thread created by forkOn will stay on the same capability for its entire lifetime (forkIO threads can migrate between capabilities according to the scheduling policy). forkOn is useful for overriding the scheduling policy when you know in advance how best to distribute the threads. The Int argument specifies a capability number (see getNumCapabilities). Typically capabilities correspond to physical processors, but the exact behaviour is implementation-dependent. The value passed to forkOn is interpreted modulo the total number of capabilities as returned by getNumCapabilities. GHC note: the number of capabilities is specified by the +RTS -N option when the program is started. Capabilities can be fixed to actual processor cores with +RTS -qa if the underlying operating system supports that, although in practice this is usually unnecessary (and may actually degrade performance in some cases - experimentation is recommended).

Like forkIOWithUnmask, but the child thread is pinned to the given CPU, as with forkOn.

The type ForeignPtr represents references to objects that are maintained in a foreign language, i.e., that are not part of the data structures usually managed by the Haskell storage manager. The essential difference between ForeignPtrs and vanilla memory references of type Ptr a is that the former may be associated with finalizers. A finalizer is a routine that is invoked when the Haskell storage manager detects that - within the Haskell heap and stack - there are no more references left that are pointing to the ForeignPtr. Typically, the finalizer will, then, invoke routines in the foreign language that free the resources bound by the foreign object. The ForeignPtr is parameterised in the same way as Ptr. The type argument of ForeignPtr should normally be an instance of class Storable.

Cf: Other, Format

currently in a foreign call

This function adds a finalizer to the given foreign object. The finalizer will run before all other finalizers for the same object which have already been registered.

Like addForeignPtrFinalizer but the finalizer is passed an additional environment parameter.

This function casts a ForeignPtr parameterised by one type into another type.

Causes the finalizers associated with a foreign pointer to be run immediately. The foreign pointer must not be used again after this function is called. If the foreign pointer does not support finalizers, this is a no-op.

Computation hWaitForInput hdl t waits until input is available on handle hdl. It returns True as soon as input is available on hdl, or False if no input is available within t milliseconds. Note that hWaitForInput waits until one or more full characters are available, which means that it needs to do decoding, and hence may fail with a decoding error. If t is less than zero, then hWaitForInput waits indefinitely. This operation may fail with:

• isEOFError if the end of file has been reached.
• a decoding error, if the input begins with an invalid byte sequence in this Handle's encoding.

NOTE for GHC users: unless you use the -threaded flag, hWaitForInput hdl t where t >= 0 will block all other Haskell threads for the duration of the call. It behaves like a safe foreign call in this respect.

Allocate some memory and return a ForeignPtr to it. The memory will be released automatically when the ForeignPtr is discarded. mallocForeignPtr is equivalent to

do { p <- malloc; newForeignPtr finalizerFree p }

although it may be implemented differently internally: you may not assume that the memory returned by mallocForeignPtr has been allocated with malloc. GHC notes: mallocForeignPtr has a heavily optimised implementation in GHC. It uses pinned memory in the garbage collected heap, so the ForeignPtr does not require a finalizer to free the memory. Use of mallocForeignPtr and associated functions is strongly recommended in preference to newForeignPtr with a finalizer.

This function is similar to mallocArray, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

This function is similar to mallocArray0, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

This function is similar to mallocForeignPtr, except that the size of the memory required is given explicitly as a number of bytes.

Turns a plain memory reference into a foreign pointer, and associates a finalizer with the reference. The finalizer will be executed after the last reference to the foreign object is dropped. There is no guarantee of promptness, however the finalizer will be executed before the program exits.