Foreign.RemotePtr

Synopsis

Toolbox for managing remote objects in Haskell.

RemotePtr

type RemotePtr a = IORef (RemoteData a)

A RemotePtr is a pointer to a foreign object.

Like a ForeignPtr, it refers to an object managed by an environment external to the Haskell runtime. Likewise, you can assign finalizers to a RemotePtr. The finalizers will be run when the Haskell runtime garbage collects this value. They can perform some cleanup operations, like freeing memory.

Unlike a ForeignPtr, the object referenced by a RemotePtr is not necessarily a block of RAM. Instead, it can refer to things like an object managed by a remote program.

withRemotePtr :: RemotePtr a -> (Coupon -> a -> IO b) -> IO b

Access the data of the RemotePtr.

While the action is being performed, it is ensured that the RemotePtr will not be garbage collected and its Coupon can be successfully redeemed at the Vendor.

addFinalizer :: RemotePtr a -> IO () -> IO ()

Add a finalizer that is run when the RemotePtr is garbage collected.

The associated coupon cannot be redeemed anymore while the finalizer runs.

destroy :: RemotePtr a -> IO ()

FIXME: Is this finalizer really run when destroy is called?

Destroy a RemotePtr and run all finalizers for it. Coupons for this pointer can no longer be redeemed.

addReachable :: RemotePtr a -> RemotePtr b -> IO ()

When dealing with several foreign objects, it is useful to model dependencies between them.

After this operation, the second RemotePtr 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 :: RemotePtr a -> IO ()

Clear all dependencies.

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

unprotectedGetCoupon :: RemotePtr a -> IO Coupon

Unprotected access the Coupon of a RemotePtr.

Note: There is no guarantee that the RemotePtr is alive after this operation and that the Coupon can be redeemed at a Vendor. Most of the time, you should use withRemotePtr instead.

Note: In particular, if you use this with unsafePerformIO, the risk is high that you only refer to the RemotePtr argument via the result just obtained, and the pointer will be garbage collected.

Coupons and Vendors

type Coupon = Text

A Coupon is a unique identifier.

It is a string of alphanumeric ASCII characters and it is intended to be sent to or received from a remote program.

The data structure Vendor associates Coupons to RemotPtr objects.

newCoupon :: Vendor a -> IO Coupon

Create a new Coupon.

WARNING: This coupon is only unique relative to this Vendor. There is no guarantee that this Coupon is globally unique, certainly not on a remote machine.

data Vendor a

A Vendor is a bijective mapping from Coupon to RemotePtr.

Every Coupon has at most one RemotePtr associated to it. A single RemotePtr will always be associated with the same Coupon.

newVendor :: IO (Vendor a)

Create a new Vendor for trading Coupons and RemotePtrs.

lookup :: Coupon -> Vendor a -> IO (Maybe (RemotePtr a))

Take a Coupon to a Vendor and maybe you'll get a RemotePtr for it.

newRemotePtr :: Coupon -> a -> Vendor a -> IO (RemotePtr a)

Create a new RemotePtr from a Coupon and register it with a Vendor.