@@ -5,6 +5,15 @@
55{-# LANGUAGE ForeignFunctionInterface #-}
66{-# LANGUAGE JavaScriptFFI #-}
77#endif
8+
9+-- |Contains 'FastWeak', a weak pointer to some value, and 'FastWeakTicket' which ensures the value referred to by a 'FastWeak' stays live while the ticket is
10+-- held (live).
11+--
12+-- On GHC or GHCJS when not built with the @fast-weak@ cabal flag, 'FastWeak' is a wrapper around the simple version of 'System.Mem.Weak.Weak' where the key
13+-- and value are the same.
14+--
15+-- On GHCJS when built with the @fast-weak@ cabal flag, 'FastWeak' is implemented directly in JS using @h$FastWeak@ and @h$FastWeakTicket@ which are a
16+-- nonstandard part of the GHCJS RTS. __FIXME__
817module Reflex.FastWeak
918 ( FastWeakTicket
1019 , FastWeak
@@ -35,29 +44,52 @@ import System.Mem.Weak
3544
3645
3746#ifdef GHCJS_FAST_WEAK
47+-- |A 'FastWeak' which has been promoted to a strong reference. 'getFastWeakTicketValue' can be used to get the referred to value without fear of @Nothing,
48+-- and 'getFastWeakTicketWeak' can be used to get the weak version.
49+--
50+-- Implemented by way of special support in the GHCJS RTS, @h$FastWeakTicket@.
3851newtype FastWeakTicket a = FastWeakTicket JSVal
3952
53+-- |A reference to some value which can be garbage collected if there are only weak references to the value left.
54+--
55+-- 'getFastWeakValue' can be used to try and obtain a strong reference to the value.
56+--
57+-- The value in a @FastWeak@ can also be kept alive by obtaining a 'FastWeakTicket' using 'getFastWeakTicket' if the value hasn't been collected yet.
58+--
59+-- Implemented by way of special support in the GHCJS RTS, @h$FastWeak@.
4060newtype FastWeak a = FastWeak JSVal
4161
4262-- Just designed to mirror JSVal, so that we can unsafeCoerce between the two
4363data Val a = Val { unVal :: a }
4464
45−-- | Coerce a JSVal that represents the heap object of a value of type 'a' into a value of type 'a'
65+-- | Coerce a JSVal that represents the heap object of a value of type @a@ into a value of type @a@
4666unsafeFromRawJSVal :: JSVal -> a
4767unsafeFromRawJSVal v = unVal (unsafeCoerce v)
4868
69+-- | Coerce a heap object of type @a@ into a 'JSVal' which represents that object.
4970unsafeToRawJSVal :: a -> JSVal
5071unsafeToRawJSVal v = unsafeCoerce (Val v)
5172#else
73+-- |A 'FastWeak' which has been promoted to a strong reference. 'getFastWeakTicketValue' can be used to get the referred to value without fear of @Nothing,
74+-- and 'getFastWeakTicketWeak' can be used to get the weak version.
5275data FastWeakTicket a = FastWeakTicket
5376 { _fastWeakTicket_val :: !a
5477 , _fastWeakTicket_weak :: {-# UNPACK #-} !(Weak a)
5578 }
5679
80+-- |A reference to some value which can be garbage collected if there are only weak references to the value left.
81+--
82+-- 'getFastWeakValue' can be used to try and obtain a strong reference to the value.
83+--
84+-- The value in a @FastWeak@ can also be kept alive by obtaining a 'FastWeakTicket' using 'getFastWeakTicket' if the value hasn't been collected yet.
85+--
86+-- Synonymous with 'Weak'.
5787type FastWeak a = Weak a
5888#endif
5989
60−-- This needs to be in IO so we know that we've relinquished the ticket
90+-- |Return the @a@ kept alive by the given 'FastWeakTicket'.
91+--
92+-- This needs to be in IO so we know that we've relinquished the ticket.
6193getFastWeakTicketValue :: FastWeakTicket a -> IO a
6294#ifdef GHCJS_FAST_WEAK
6395getFastWeakTicketValue t = do
@@ -69,6 +101,7 @@ foreign import javascript unsafe "$r = $1.val;" js_ticketVal :: FastWeakTicket a
69101getFastWeakTicketValue = return . _fastWeakTicket_val
70102#endif
71103
104+-- |Get the value referred to by a 'FastWeak' if it hasn't yet been collected, or @Nothing@ if it has been collected.
72105getFastWeakValue :: FastWeak a -> IO (Maybe a)
73106#ifdef GHCJS_FAST_WEAK
74107getFastWeakValue w = do
@@ -84,6 +117,8 @@ foreign import javascript unsafe "$r = ($1.ticket === null) ? null : $1.ticket.v
84117getFastWeakValue = deRefWeak
85118#endif
86119
120+-- |Try to create a 'FastWeakTicket' for the given 'FastWeak' which will ensure the referred to value remains alive. Returns @Just@ if the value hasn't been
121+-- collected and a ticket can therefore be obtained, @Nothing@ if it's been collected.
87122getFastWeakTicket :: forall a. FastWeak a -> IO (Maybe (FastWeakTicket a))
88123#ifdef GHCJS_FAST_WEAK
89124getFastWeakTicket w = do
@@ -103,8 +138,10 @@ getFastWeakTicket w = do
103138 }
104139#endif
105140
106−-- I think it's fine if this is lazy - it'll retain the 'a', but so would the output; we just need to make sure it's forced before we start relying on the associated FastWeak to actually be weak
141+-- |Create a 'FastWeakTicket' directly from a value, creating a 'FastWeak' in the process which can be obtained with 'getFastWeakTicketValue'.
107142mkFastWeakTicket :: a -> IO (FastWeakTicket a)
143+-- I think it's fine if this is lazy - it'll retain the 'a', but so would the output; we just need to make sure it's forced before we start relying on the
144+-- associated FastWeak to actually be weak
108145#ifdef GHCJS_FAST_WEAK
109146mkFastWeakTicket v = js_fastWeakTicket (unsafeToRawJSVal v)
110147
@@ -119,11 +156,15 @@ mkFastWeakTicket v = do
119156 }
120157#endif
121158
159+-- |Demote a 'FastWeakTicket' which ensures the value is alive to a 'FastWeak' which doesn't. Note that unless the ticket or another for the same 'FastWeak' is
160+-- held some other way the value might be collected immediately.
161+getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
122162-- Needs IO so that it can force the value - otherwise, could end up with a reference to the Ticket, which would retain the value
123163#ifdef GHCJS_FAST_WEAK
124−foreign import javascript unsafe "$r = $1.weak;" getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
164+foreign import javascript unsafe "$r = $1.weak;" getFastWeakTicketWeak' :: FastWeakTicket a -> IO (FastWeak a)
165+{-# INLINE getFastWeakTicketWeak #-}
166+getFastWeakTicketWeak = getFastWeakTicketWeak'
125167#else
126−getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
127168getFastWeakTicketWeak = return . _fastWeakTicket_weak
128169#endif
129170