[Gtk2hs-commit] (main branch): Update System.GIO.Async.Cancellable module

[Andy S. <And...@co...>]

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.
    }