primitive-0.9.0.0: Primitive memory-related operations

Copyright | (c) Justin Bonnar 2011 Roman Leshchinskiy 2011-2012
License | BSD-style
Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au>
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Data.Primitive.MutVar

Description

Primitive boxed mutable variables. This is a generalization of Data.IORef, Data.STRef and Data.STRef.Lazy to work in any `PrimMonad`.

Synopsis

- data MutVar s a = MutVar (MutVar# s a)
- newMutVar :: PrimMonad m => a -> m (MutVar (PrimState m) a)
- readMutVar :: PrimMonad m => MutVar (PrimState m) a -> m a
- writeMutVar :: PrimMonad m => MutVar (PrimState m) a -> a -> m ()
- atomicModifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b
- atomicModifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b
- modifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
- modifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()

# Documentation

data MutVar s a #

A `MutVar` behaves like a single-element mutable array associated with a primitive state token.

Constructors

MutVar (MutVar# s a) |

#### Instances

Instances details

Eq (MutVar s a) # |
Instance details Defined in Data.Primitive.MutVar Methods (==) :: MutVar s a -> MutVar s a -> Bool # (/=) :: MutVar s a -> MutVar s a -> Bool #

newMutVar :: PrimMonad m => a -> m (MutVar (PrimState m) a) #

Create a new `MutVar` with the specified initial value.

readMutVar :: PrimMonad m => MutVar (PrimState m) a -> m a #

Read the value of a `MutVar`.

writeMutVar :: PrimMonad m => MutVar (PrimState m) a -> a -> m () #

Write a new value into a `MutVar`.

atomicModifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b #

Atomically mutate the contents of a `MutVar`.

This function is useful for using `MutVar` in a safe way in a multithreaded program. If you only have one `MutVar`, then using `atomicModifyMutVar` to access and modify it will prevent race conditions.

Extending the atomicity to multiple `MutVar`s is problematic, so if you need to do anything more complicated, using `MVar` instead is a good idea.

`atomicModifyMutVar` does not apply the function strictly. This means if a program calls `atomicModifyMutVar` many times, but seldom uses the value, thunks will pile up in memory resulting in a space leak. To avoid this problem, use `atomicModifyMutVar'` instead.

atomicModifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b #

Strict version of `atomicModifyMutVar`. This forces both the value stored in the `MutVar` as well as the value returned.

modifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m () #

Mutate the contents of a `MutVar`.

`modifyMutVar` does not apply the function strictly. This means if a program calls `modifyMutVar` many times, but seldom uses the value, thunks will pile up in memory resulting in a space leak. To avoid this problem, use `modifyMutVar'` instead.

modifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m () #

Strict version of `modifyMutVar`.