{-# LINE 2 "./System/GIO/Async/Cancellable.chs" #-}
-- GIMP Toolkit (GTK) Binding for Haskell: binding to gio -*-haskell-*-
--
-- Author : Peter Gavin
-- Created: 13-Oct-2008
--
-- Copyright (c) 2008 Peter Gavin
--
-- This library is free software: you can redistribute it and/or
-- modify it under the terms of the GNU Lesser General Public License
-- as published by the Free Software Foundation, either version 3 of
-- the License, or (at your option) any later version.
--
-- This library is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-- Lesser General Public License for more details.
--
-- You should have received a copy of the GNU Lesser General Public
-- License along with this program. If not, see
-- <http:
--
-- GIO, the C library which this Haskell library depends on, is
-- available under LGPL Version 2. The documentation included with
-- this library is based on the original GIO documentation.
--
-- | Maintainer : gtk2hs-devel@lists.sourceforge.net
-- Stability : alpha
-- Portability : portable (depends on GHC)
module System.GIO.Async.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
    cancellableNew,
    cancellableIsCancelled,
    cancellableThrowErrorIfCancelled,
    cancellableGetCurrent,
    cancellablePopCurrent,
    cancellablePushCurrent,
    cancellableReset,
    cancellableCancel,

-- * Signals
    cancellableCancelled
    ) where

import Control.Monad
import Data.Maybe (fromMaybe)
import System.Glib.FFI
import System.Glib.GError
import System.Glib.GObject
import System.Glib.Signals
import System.GIO.Signals
{-# LINE 60 "./System/GIO/Async/Cancellable.chs" #-}
import System.GIO.Types
{-# LINE 61 "./System/GIO/Async/Cancellable.chs" #-}


{-# LINE 63 "./System/GIO/Async/Cancellable.chs" #-}

-- | 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.
cancellableNew :: IO Cancellable
cancellableNew :: IO Cancellable
cancellableNew =
    (ForeignPtr Cancellable -> Cancellable, FinalizerPtr Cancellable)
-> IO (Ptr Cancellable) -> IO Cancellable
forall obj.
GObjectClass obj =>
(ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj
wrapNewGObject (ForeignPtr Cancellable -> Cancellable, FinalizerPtr Cancellable)
forall {a}. (ForeignPtr Cancellable -> Cancellable, FinalizerPtr a)
mkCancellable (IO (Ptr Cancellable) -> IO Cancellable)
-> IO (Ptr Cancellable) -> IO Cancellable
forall a b. (a -> b) -> a -> b
$
    IO (Ptr Cancellable)
g_cancellable_new
{-# LINE 75 "./System/GIO/Async/Cancellable.chs" #-}

-- | 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.
cancellableIsCancelled :: Cancellable -> IO Bool
cancellableIsCancelled =
    (CInt -> Bool) -> IO CInt -> IO Bool
forall (m :: * -> *) a1 r. Monad m => (a1 -> r) -> m a1 -> m r
liftM CInt -> Bool
forall a. (Eq a, Num a) => a -> Bool
toBool (IO CInt -> IO Bool)
-> (Cancellable -> IO CInt) -> Cancellable -> IO Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (\(Cancellable ForeignPtr Cancellable
arg1) -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO CInt) -> IO CInt
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO CInt) -> IO CInt)
-> (Ptr Cancellable -> IO CInt) -> IO CInt
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> IO CInt
g_cancellable_is_cancelled Ptr Cancellable
argPtr1)
{-# LINE 81 "./System/GIO/Async/Cancellable.chs" #-}

-- | If the cancellable is cancelled, throws a 'GError' to notify that the operation was cancelled.
cancellableThrowErrorIfCancelled :: Cancellable -> IO ()
cancellableThrowErrorIfCancelled :: Cancellable -> IO ()
cancellableThrowErrorIfCancelled Cancellable
cancellable =
    (Ptr (Ptr ()) -> IO ()) -> IO ()
forall a. (Ptr (Ptr ()) -> IO a) -> IO a
propagateGError ((Ptr (Ptr ()) -> IO ()) -> IO ())
-> (Ptr (Ptr ()) -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr (Ptr ())
gErrorPtr -> do
      (\(Cancellable ForeignPtr Cancellable
arg1) Ptr (Ptr ())
arg2 -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO CInt) -> IO CInt
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO CInt) -> IO CInt)
-> (Ptr Cancellable -> IO CInt) -> IO CInt
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> Ptr (Ptr ()) -> IO CInt
g_cancellable_set_error_if_cancelled Ptr Cancellable
argPtr1 Ptr (Ptr ())
arg2) Cancellable
cancellable Ptr (Ptr ())
gErrorPtr
      () -> IO ()
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return ()

-- | 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.
cancellableGetCurrent :: IO (Maybe Cancellable)
cancellableGetCurrent =
    (IO (Ptr Cancellable) -> IO Cancellable)
-> IO (Ptr Cancellable) -> IO (Maybe Cancellable)
forall a. (IO (Ptr a) -> IO a) -> IO (Ptr a) -> IO (Maybe a)
maybeNull ((ForeignPtr Cancellable -> Cancellable, FinalizerPtr Cancellable)
-> IO (Ptr Cancellable) -> IO Cancellable
forall obj.
GObjectClass obj =>
(ForeignPtr obj -> obj, FinalizerPtr obj) -> IO (Ptr obj) -> IO obj
makeNewGObject (ForeignPtr Cancellable -> Cancellable, FinalizerPtr Cancellable)
forall {a}. (ForeignPtr Cancellable -> Cancellable, FinalizerPtr a)
mkCancellable) (IO (Ptr Cancellable) -> IO (Maybe Cancellable))
-> IO (Ptr Cancellable) -> IO (Maybe Cancellable)
forall a b. (a -> b) -> a -> b
$
    IO (Ptr Cancellable)
g_cancellable_get_current
{-# LINE 95 "./System/GIO/Async/Cancellable.chs" #-}

-- | Pops cancellable off the cancellable stack (verifying that cancellable is on the top of the stack).
cancellablePopCurrent :: Maybe Cancellable -> IO ()
cancellablePopCurrent :: Maybe Cancellable -> IO ()
cancellablePopCurrent Maybe Cancellable
cancellable =
      (\(Cancellable ForeignPtr Cancellable
arg1) -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO ()) -> IO ())
-> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> IO ()
g_cancellable_pop_current Ptr Cancellable
argPtr1)
{-# LINE 100 "./System/GIO/Async/Cancellable.chs" #-}
         (Cancellable -> Maybe Cancellable -> Cancellable
forall a. a -> Maybe a -> a
fromMaybe (ForeignPtr Cancellable -> Cancellable
Cancellable ForeignPtr Cancellable
forall a. ForeignPtr a
nullForeignPtr) Maybe Cancellable
cancellable)

-- | Pushes cancellable onto the cancellable stack. The current cancllable can then be received 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.
cancellablePushCurrent :: Maybe Cancellable -> IO ()
cancellablePushCurrent :: Maybe Cancellable -> IO ()
cancellablePushCurrent Maybe Cancellable
cancellable =
      (\(Cancellable ForeignPtr Cancellable
arg1) -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO ()) -> IO ())
-> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> IO ()
g_cancellable_push_current Ptr Cancellable
argPtr1)
{-# LINE 113 "./System/GIO/Async/Cancellable.chs" #-}
         (Cancellable -> Maybe Cancellable -> Cancellable
forall a. a -> Maybe a -> a
fromMaybe (ForeignPtr Cancellable -> Cancellable
Cancellable ForeignPtr Cancellable
forall a. ForeignPtr a
nullForeignPtr) Maybe Cancellable
cancellable)

-- | Resets cancellable to its uncancelled state.
cancellableReset :: Cancellable -> IO ()
cancellableReset :: Cancellable -> IO ()
cancellableReset = (\(Cancellable ForeignPtr Cancellable
arg1) -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO ()) -> IO ())
-> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> IO ()
g_cancellable_reset Ptr Cancellable
argPtr1)
{-# LINE 118 "./System/GIO/Async/Cancellable.chs" #-}

-- | 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.
cancellableCancel :: Cancellable -> IO ()
cancellableCancel :: Cancellable -> IO ()
cancellableCancel = (\(Cancellable ForeignPtr Cancellable
arg1) -> ForeignPtr Cancellable -> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Cancellable
arg1 ((Ptr Cancellable -> IO ()) -> IO ())
-> (Ptr Cancellable -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Cancellable
argPtr1 ->Ptr Cancellable -> IO ()
g_cancellable_cancel Ptr Cancellable
argPtr1)
{-# LINE 131 "./System/GIO/Async/Cancellable.chs" #-}

-- | 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.
cancellableCancelled :: Signal Cancellable (IO ())
cancellableCancelled :: Signal Cancellable (IO ())
cancellableCancelled =
    (Bool -> Cancellable -> IO () -> IO (ConnectId Cancellable))
-> Signal Cancellable (IO ())
forall object handler.
(Bool -> object -> handler -> IO (ConnectId object))
-> Signal object handler
Signal ((Bool -> Cancellable -> IO () -> IO (ConnectId Cancellable))
 -> Signal Cancellable (IO ()))
-> (Bool -> Cancellable -> IO () -> IO (ConnectId Cancellable))
-> Signal Cancellable (IO ())
forall a b. (a -> b) -> a -> b
$ SignalName
-> Bool -> Cancellable -> IO () -> IO (ConnectId Cancellable)
forall obj.
GObjectClass obj =>
SignalName -> Bool -> obj -> IO () -> IO (ConnectId obj)
connect_NONE__NONE SignalName
"cancelled"

foreign import ccall safe "g_cancellable_new"
  g_cancellable_new :: (IO (Ptr Cancellable))

foreign import ccall safe "g_cancellable_is_cancelled"
  g_cancellable_is_cancelled :: ((Ptr Cancellable) -> (IO CInt))

foreign import ccall safe "g_cancellable_set_error_if_cancelled"
  g_cancellable_set_error_if_cancelled :: ((Ptr Cancellable) -> ((Ptr (Ptr ())) -> (IO CInt)))

foreign import ccall safe "g_cancellable_get_current"
  g_cancellable_get_current :: (IO (Ptr Cancellable))

foreign import ccall safe "g_cancellable_pop_current"
  g_cancellable_pop_current :: ((Ptr Cancellable) -> (IO ()))

foreign import ccall safe "g_cancellable_push_current"
  g_cancellable_push_current :: ((Ptr Cancellable) -> (IO ()))

foreign import ccall safe "g_cancellable_reset"
  g_cancellable_reset :: ((Ptr Cancellable) -> (IO ()))

foreign import ccall safe "g_cancellable_cancel"
  g_cancellable_cancel :: ((Ptr Cancellable) -> (IO ()))