Foreign.Coupon

Synopsis

References to remote objects. Offers unique tokens (Coupon) for communication. Supports garbage collection and finalizers.

Documentation

type Coupon = ByteString

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

Remote boothes are a mapping from Coupon to Item.

Prize boothes are neutral concerning garbage collection, they do not keep items alive. Moreover, items will be deleted from the booth when they are garbage collected.

newPrizeBooth :: IO (PrizeBooth a)

Create a new prize booth for creating items and trading coupons.

lookup :: Coupon -> PrizeBooth a -> IO (Maybe (Item a))

Take a coupon to the prize booth and maybe you'll get an item for it.

type Item a = IORef (ItemData a)

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)

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 b

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 ()

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 ()

Destroy an item and run all finalizers for it. Coupons for this item can no longer be redeemed.

addReachable :: Item a -> Item a -> IO ()

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 ()

Clear all dependencies.

Reachability of this Item no longer implies reachability of other items, as formerly implied by calls to addReachable.