--- This function can be used to express liveness
--- dependencies between 'ForeignPtr's: for
--- example, if the finalizer for one
--- 'ForeignPtr' touches a second
--- 'ForeignPtr', then it is ensured that the
--- second 'ForeignPtr' will stay alive at
--- least as long as the first. This can be useful when you
--- want to manipulate /interior pointers/ to
--- a foreign structure: you can use
--- 'touchForeignObj' to express the
--- requirement that the exterior pointer must not be finalized
--- until the interior pointer is no longer referenced.
+-- Note that this function should not be used to express liveness
+-- dependencies between 'ForeignPtr's. For example, if the finalizer
+-- for a 'ForeignPtr' @F1@ calls 'touchForeignPtr' on a second
+-- 'ForeignPtr' @F2@, then the only guarantee is that the finalizer
+-- for @F2@ is never started before the finalizer for @F1@. They
+-- might be started together if for example both @F1@ and @F2@ are
+-- otherwise unreachable, and in that case the scheduler might end up
+-- running the finalizer for @F2@ first.
+--
+-- In general, it is not recommended to use finalizers on separate
+-- objects with ordering constraints between them. To express the
+-- ordering robustly requires explicit synchronisation using @MVar@s
+-- between the finalizers, but even then the runtime sometimes runs
+-- multiple finalizers sequentially in a single thread (for
+-- performance reasons), so synchronisation between finalizers could
+-- result in artificial deadlock.
+--