| Safe Haskell | None |
|---|
Foreign.Coupon
Contents
- type Coupon = ByteString
- data PrizeBooth a
- newPrizeBooth :: IO (PrizeBooth a)
- lookup :: Coupon -> PrizeBooth a -> IO (Maybe (Item a))
- type Item a = IORef (ItemData a)
- newItem :: PrizeBooth a -> a -> IO (Item a)
- withItem :: Item a -> (Coupon -> a -> IO b) -> IO b
- addFinalizer :: Item a -> IO () -> IO ()
- destroy :: Item a -> IO ()
- addReachable :: Item a -> Item a -> IO ()
- clearReachable :: Item a -> IO ()
Synopsis
References to remote objects.
Offers unique tokens (Coupon) for communication.
Supports garbage collection and finalizers.
Documentation
type Coupon = ByteStringSource
Coupons can be used as a proxy for Item.
The important point is that coupons can be serialized and sent over a remote connection.
Coupons are in bijection with items: Different coupons will yield different items while the same item will always be associated to the same coupon.
data PrizeBooth a Source
newPrizeBooth :: IO (PrizeBooth a)Source
Create a new prize booth for creating items and trading coupons.
lookup :: Coupon -> PrizeBooth a -> IO (Maybe (Item a))Source
Take a coupon to the prize booth and maybe you'll get an item for it.
type Item a = IORef (ItemData a)Source
Items represent foreign objects. The intended use case is that these objects do not live in RAM, but are only accessible via a remote connection.
The foreign object can be accessed by means of the item data of type a.
newItem :: PrizeBooth a -> a -> IO (Item a)Source
Create a new item, which can be exchanged for a coupon at an associated prize booth.
The item can become unreachable, at which point it will be garbage collected, the finalizers will be run and its coupon ceases to be valid.
withItem :: Item a -> (Coupon -> a -> IO b) -> IO bSource
Perform an action with the item.
While the action is being performed, it is ensured that the item will not be garbage collected and its coupon can be succesfully redeemed at the prize booth.
addFinalizer :: Item a -> IO () -> IO ()Source
Add a finalizer that is run when the item is garbage collected.
The coupon cannot be redeemed anymore while the finalizer runs.
destroy :: Item a -> IO ()Source
Destroy an item and run all finalizers for it. Coupons for this item can no longer be redeemed.
addReachable :: Item a -> Item a -> IO ()Source
When dealing with several foreign objects, it is useful to model dependencies between them.
After this operation, the second Item will be reachable
whenever the first one is reachable.
For instance, you should call this function when the second foreign object
is actually a subobject of the first one.
Note: It is possible to model dependencies in the parent data,
but the addReachable method is preferrable,
as it allows all child object to be garbage collected at once.
clearReachable :: Item a -> IO ()Source
Clear all dependencies.
Reachability of this Item no longer implies reachability
of other items, as formerly implied by calls to addReachable.