diffing dir...
Sun Aug 15 14:08:37 EDT 2010 Andy Stewart <laz...@gm...>
* Update System.GIO.Async.Cancellable module
Ignore-this: 9ab8b1149393518e6bc650cc857c8775
{
hunk ./gio/System/GIO/Async/Cancellable.chs 31
- Cancellable,
+-- * Details
+-- | 'Cancellable' is a thread-safe operation cancellation stack used throughout GIO to allow for
+-- cancellation of synchronous and asynchronous operations.
+
+-- * Types [_$_]
+ Cancellable (..),
+ CancellableClass,
+
+-- * Methods [_$_]
hunk ./gio/System/GIO/Async/Cancellable.chs 48
+
+-- * Signals
hunk ./gio/System/GIO/Async/Cancellable.chs 54
-
hunk ./gio/System/GIO/Async/Cancellable.chs 56
+import System.Glib.GObject
+import System.Glib.Signals
+{#import System.GIO.Base#}
hunk ./gio/System/GIO/Async/Cancellable.chs 60
-
-import System.GIO.Base
hunk ./gio/System/GIO/Async/Cancellable.chs 64
+-- | Creates a new 'Cancellable' object.
+-- [_$_]
+-- Applications that want to start one or more operations that should be cancellable should create a
+-- 'Cancellable' and pass it to the operations.
+-- [_$_]
+-- One 'Cancellable' can be used in multiple consecutive operations, but not in multiple concurrent
+-- operations.
hunk ./gio/System/GIO/Async/Cancellable.chs 73
- {# call cancellable_new #} >>= takeGObject
+ constructNewGObject mkCancellable $
+ {# call cancellable_new #}
hunk ./gio/System/GIO/Async/Cancellable.chs 76
-cancellableIsCancelled :: Cancellable -> IO Bool
+-- | Checks if a cancellable job has been cancelled.
+cancellableIsCancelled :: Cancellable [_$_]
+ -> IO Bool -- ^ returns 'True' if cancellable is cancelled, 'False' if called with 'Nothing' or if item is not cancelled.
hunk ./gio/System/GIO/Async/Cancellable.chs 82
-cancellableThrowErrorIfCancelled :: Cancellable -> IO ()
+-- | If the cancellable is cancelled, sets the error to notify that the operation was cancelled.
+cancellableThrowErrorIfCancelled :: Cancellable [_$_]
+ -> IO Bool -- ^ returns 'True' if cancellable was cancelled, 'False' if it was not. [_$_]
hunk ./gio/System/GIO/Async/Cancellable.chs 86
- propagateGError $ \gErrorPtr -> do
+ liftM toBool $
+ propagateGError $ \gErrorPtr -> [_$_]
hunk ./gio/System/GIO/Async/Cancellable.chs 89
- return ()
hunk ./gio/System/GIO/Async/Cancellable.chs 90
-cancellableGetCurrent :: IO (Maybe Cancellable)
+-- | Gets the top cancellable from the stack.
+cancellableGetCurrent :: [_$_]
+ IO (Maybe Cancellable) -- ^ returns a 'Cancellable' from the top of the stack, or 'Nothing' if the stack is empty.
hunk ./gio/System/GIO/Async/Cancellable.chs 94
- {# call cancellable_get_current #} >>= maybePeek takeGObject
+ maybeNull (constructNewGObject mkCancellable) $
+ {# call cancellable_get_current #} [_$_]
hunk ./gio/System/GIO/Async/Cancellable.chs 97
+-- | Pops cancellable off the cancellable stack (verifying that cancellable is on the top of the stack).
hunk ./gio/System/GIO/Async/Cancellable.chs 104
+-- | Pushes cancellable onto the cancellable stack. The current cancllable can then be recieved using
+-- 'cancellableGetCurrent' .
+-- [_$_]
+-- This is useful when implementing cancellable operations in code that does not allow you to pass down
+-- the cancellable object.
+-- [_$_]
+-- This is typically called automatically by e.g. 'File' operations, so you rarely have to call this
+-- yourself.
hunk ./gio/System/GIO/Async/Cancellable.chs 118
+-- | Resets cancellable to its uncancelled state.
hunk ./gio/System/GIO/Async/Cancellable.chs 122
+-- | Will set cancellable to cancelled, and will emit the "cancelled" signal. (However, see the warning
+-- about race conditions in the documentation for that signal if you are planning to connect to it.)
+-- [_$_]
+-- This function is thread-safe. In other words, you can safely call it from a thread other than the
+-- one running the operation that was passed the cancellable.
+-- [_$_]
+-- The convention within gio is that cancelling an asynchronous operation causes it to complete
+-- asynchronously. That is, if you cancel the operation from the same thread in which it is running,
+-- then the operation's 'AsyncReadyCallback' will not be invoked until the application returns to the
+-- main loop.
hunk ./gio/System/GIO/Async/Cancellable.chs 135
+-- | Emitted when the operation has been cancelled.
+-- [_$_]
+-- Can be used by implementations of cancellable operations. If the operation is cancelled from another
+-- thread, the signal will be emitted in the thread that cancelled the operation, not the thread that
+-- is running the operation.
+-- [_$_]
+-- Note that disconnecting from this signal (or any signal) in a multi-threaded program is prone to
+-- race conditions. For instance it is possible that a signal handler may be invoked even after a call
+-- to 'signalHandlerDisconnect' for that handler has already returned.
+-- [_$_]
+-- There is also a problem when cancellation happen right before connecting to the signal. If this
+-- happens the signal will unexpectedly not be emitted, and checking before connecting to the signal
+-- leaves a race condition where this is still happening.
}
|
