{- |
Copyright  : Will Thompson, Iñaki García Etxebarria and Jonas Platte
License    : LGPL-2.1
Maintainer : Iñaki García Etxebarria (garetxe@gmail.com)

The 'GI.GLib.Unions.Mutex.Mutex' struct is an opaque data structure to represent a mutex
(mutual exclusion). It can be used to protect data against shared
access.

Take for example the following function:

=== /C code/
>
>  int
>  give_me_next_number (void)
>  {
>    static int current_number = 0;
>
>    // now do a very complicated calculation to calculate the new
>    // number, this might for example be a random number generator
>    current_number = calc_next_number (current_number);
>
>    return current_number;
>  }

It is easy to see that this won\'t work in a multi-threaded
application. There current_number must be protected against shared
access. A 'GI.GLib.Unions.Mutex.Mutex' can be used as a solution to this problem:

=== /C code/
>
>  int
>  give_me_next_number (void)
>  {
>    static GMutex mutex;
>    static int current_number = 0;
>    int ret_val;
>
>    g_mutex_lock (&mutex);
>    ret_val = current_number = calc_next_number (current_number);
>    g_mutex_unlock (&mutex);
>
>    return ret_val;
>  }

Notice that the 'GI.GLib.Unions.Mutex.Mutex' is not initialised to any particular value.
Its placement in static storage ensures that it will be initialised
to all-zeros, which is appropriate.

If a 'GI.GLib.Unions.Mutex.Mutex' is placed in other contexts (eg: embedded in a struct)
then it must be explicitly initialised using 'GI.GLib.Unions.Mutex.mutexInit'.

A 'GI.GLib.Unions.Mutex.Mutex' should only be accessed via g_mutex_ functions.
-}

#define ENABLE_OVERLOADING \
       (!defined(__HADDOCK_VERSION__))

module GI.GLib.Unions.Mutex
    ( 

-- * Exported types
    Mutex(..)                               ,
    newZeroMutex                            ,
    noMutex                                 ,


 -- * Methods
-- ** clear #method:clear#

#if ENABLE_OVERLOADING
    MutexClearMethodInfo                    ,
#endif
    mutexClear                              ,


-- ** init #method:init#

#if ENABLE_OVERLOADING
    MutexInitMethodInfo                     ,
#endif
    mutexInit                               ,


-- ** lock #method:lock#

#if ENABLE_OVERLOADING
    MutexLockMethodInfo                     ,
#endif
    mutexLock                               ,


-- ** trylock #method:trylock#

#if ENABLE_OVERLOADING
    MutexTrylockMethodInfo                  ,
#endif
    mutexTrylock                            ,


-- ** unlock #method:unlock#

#if ENABLE_OVERLOADING
    MutexUnlockMethodInfo                   ,
#endif
    mutexUnlock                             ,




    ) where

import Data.GI.Base.ShortPrelude
import qualified Data.GI.Base.ShortPrelude as SP
import qualified Data.GI.Base.Overloading as O
import qualified Prelude as P

import qualified Data.GI.Base.Attributes as GI.Attributes
import qualified Data.GI.Base.ManagedPtr as B.ManagedPtr
import qualified Data.GI.Base.GError as B.GError
import qualified Data.GI.Base.GVariant as B.GVariant
import qualified Data.GI.Base.GValue as B.GValue
import qualified Data.GI.Base.GParamSpec as B.GParamSpec
import qualified Data.GI.Base.CallStack as B.CallStack
import qualified Data.Text as T
import qualified Data.ByteString.Char8 as B
import qualified Data.Map as Map
import qualified Foreign.Ptr as FP


-- | Memory-managed wrapper type.
newtype Mutex = Mutex (ManagedPtr Mutex)
instance WrappedPtr Mutex where
    wrappedPtrCalloc :: IO (Ptr Mutex)
wrappedPtrCalloc = Int -> IO (Ptr Mutex)
forall a. Int -> IO (Ptr a)
callocBytes 8
    wrappedPtrCopy :: Mutex -> IO Mutex
wrappedPtrCopy = \p :: Mutex
p -> Mutex -> (Ptr Mutex -> IO Mutex) -> IO Mutex
forall a c.
(HasCallStack, ManagedPtrNewtype a) =>
a -> (Ptr a -> IO c) -> IO c
withManagedPtr Mutex
p (Int -> Ptr Mutex -> IO (Ptr Mutex)
forall a. WrappedPtr a => Int -> Ptr a -> IO (Ptr a)
copyBytes 8 (Ptr Mutex -> IO (Ptr Mutex))
-> (Ptr Mutex -> IO Mutex) -> Ptr Mutex -> IO Mutex
forall (m :: * -> *) a b c.
Monad m =>
(a -> m b) -> (b -> m c) -> a -> m c
>=> (ManagedPtr Mutex -> Mutex) -> Ptr Mutex -> IO Mutex
forall a.
(HasCallStack, WrappedPtr a) =>
(ManagedPtr a -> a) -> Ptr a -> IO a
wrapPtr ManagedPtr Mutex -> Mutex
Mutex)
    wrappedPtrFree :: Maybe (FunPtr (Ptr Mutex -> IO ()))
wrappedPtrFree = FunPtr (Ptr Mutex -> IO ()) -> Maybe (FunPtr (Ptr Mutex -> IO ()))
forall a. a -> Maybe a
Just FunPtr (Ptr Mutex -> IO ())
forall a. FunPtr (Ptr a -> IO ())
ptr_to_g_free

-- | Construct a `Mutex` struct initialized to zero.
newZeroMutex :: MonadIO m => m Mutex
newZeroMutex :: m Mutex
newZeroMutex = IO Mutex -> m Mutex
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO Mutex -> m Mutex) -> IO Mutex -> m Mutex
forall a b. (a -> b) -> a -> b
$ IO (Ptr Mutex)
forall a. WrappedPtr a => IO (Ptr a)
wrappedPtrCalloc IO (Ptr Mutex) -> (Ptr Mutex -> IO Mutex) -> IO Mutex
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (ManagedPtr Mutex -> Mutex) -> Ptr Mutex -> IO Mutex
forall a.
(HasCallStack, WrappedPtr a) =>
(ManagedPtr a -> a) -> Ptr a -> IO a
wrapPtr ManagedPtr Mutex -> Mutex
Mutex

instance tag ~ 'AttrSet => Constructible Mutex tag where
    new :: (ManagedPtr Mutex -> Mutex) -> [AttrOp Mutex tag] -> m Mutex
new _ attrs :: [AttrOp Mutex tag]
attrs = do
        Mutex
o <- m Mutex
forall (m :: * -> *). MonadIO m => m Mutex
newZeroMutex
        Mutex -> [AttrOp Mutex 'AttrSet] -> m ()
forall o (m :: * -> *).
MonadIO m =>
o -> [AttrOp o 'AttrSet] -> m ()
GI.Attributes.set Mutex
o [AttrOp Mutex tag]
[AttrOp Mutex 'AttrSet]
attrs
        Mutex -> m Mutex
forall (m :: * -> *) a. Monad m => a -> m a
return Mutex
o


-- | A convenience alias for `Nothing` :: `Maybe` `Mutex`.
noMutex :: Maybe Mutex
noMutex :: Maybe Mutex
noMutex = Maybe Mutex
forall a. Maybe a
Nothing


#if ENABLE_OVERLOADING
instance O.HasAttributeList Mutex
type instance O.AttributeList Mutex = MutexAttributeList
type MutexAttributeList = ('[ ] :: [(Symbol, *)])
#endif

-- method Mutex::clear
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "mutex", argType = TInterface (Name {namespace = "GLib", name = "Mutex"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "an initialized #GMutex", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_mutex_clear" g_mutex_clear :: 
    Ptr Mutex ->                            -- mutex : TInterface (Name {namespace = "GLib", name = "Mutex"})
    IO ()

{- |
Frees the resources allocated to a mutex with 'GI.GLib.Unions.Mutex.mutexInit'.

This function should not be used with a 'GI.GLib.Unions.Mutex.Mutex' that has been
statically allocated.

Calling 'GI.GLib.Unions.Mutex.mutexClear' on a locked mutex leads to undefined
behaviour.

Sine: 2.32
-}
mutexClear ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    Mutex
    {- ^ /@mutex@/: an initialized 'GI.GLib.Unions.Mutex.Mutex' -}
    -> m ()
mutexClear :: Mutex -> m ()
mutexClear mutex :: Mutex
mutex = IO () -> m ()
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
    Ptr Mutex
mutex' <- Mutex -> IO (Ptr Mutex)
forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
unsafeManagedPtrGetPtr Mutex
mutex
    Ptr Mutex -> IO ()
g_mutex_clear Ptr Mutex
mutex'
    Mutex -> IO ()
forall a. ManagedPtrNewtype a => a -> IO ()
touchManagedPtr Mutex
mutex
    () -> IO ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

#if ENABLE_OVERLOADING
data MutexClearMethodInfo
instance (signature ~ (m ()), MonadIO m) => O.MethodInfo MutexClearMethodInfo Mutex signature where
    overloadedMethod _ = mutexClear

#endif

-- method Mutex::init
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "mutex", argType = TInterface (Name {namespace = "GLib", name = "Mutex"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "an uninitialized #GMutex", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_mutex_init" g_mutex_init :: 
    Ptr Mutex ->                            -- mutex : TInterface (Name {namespace = "GLib", name = "Mutex"})
    IO ()

{- |
Initializes a 'GI.GLib.Unions.Mutex.Mutex' so that it can be used.

This function is useful to initialize a mutex that has been
allocated on the stack, or as part of a larger structure.
It is not necessary to initialize a mutex that has been
statically allocated.


=== /C code/
>
>  typedef struct {
>    GMutex m;
>    ...
>  } Blob;
>
>Blob *b;
>
>b = g_new (Blob, 1);
>g_mutex_init (&b->m);


To undo the effect of 'GI.GLib.Unions.Mutex.mutexInit' when a mutex is no longer
needed, use 'GI.GLib.Unions.Mutex.mutexClear'.

Calling 'GI.GLib.Unions.Mutex.mutexInit' on an already initialized 'GI.GLib.Unions.Mutex.Mutex' leads
to undefined behaviour.

/Since: 2.32/
-}
mutexInit ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    Mutex
    {- ^ /@mutex@/: an uninitialized 'GI.GLib.Unions.Mutex.Mutex' -}
    -> m ()
mutexInit :: Mutex -> m ()
mutexInit mutex :: Mutex
mutex = IO () -> m ()
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
    Ptr Mutex
mutex' <- Mutex -> IO (Ptr Mutex)
forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
unsafeManagedPtrGetPtr Mutex
mutex
    Ptr Mutex -> IO ()
g_mutex_init Ptr Mutex
mutex'
    Mutex -> IO ()
forall a. ManagedPtrNewtype a => a -> IO ()
touchManagedPtr Mutex
mutex
    () -> IO ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

#if ENABLE_OVERLOADING
data MutexInitMethodInfo
instance (signature ~ (m ()), MonadIO m) => O.MethodInfo MutexInitMethodInfo Mutex signature where
    overloadedMethod _ = mutexInit

#endif

-- method Mutex::lock
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "mutex", argType = TInterface (Name {namespace = "GLib", name = "Mutex"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GMutex", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_mutex_lock" g_mutex_lock :: 
    Ptr Mutex ->                            -- mutex : TInterface (Name {namespace = "GLib", name = "Mutex"})
    IO ()

{- |
Locks /@mutex@/. If /@mutex@/ is already locked by another thread, the
current thread will block until /@mutex@/ is unlocked by the other
thread.

'GI.GLib.Unions.Mutex.Mutex' is neither guaranteed to be recursive nor to be
non-recursive.  As such, calling 'GI.GLib.Unions.Mutex.mutexLock' on a 'GI.GLib.Unions.Mutex.Mutex' that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks).
-}
mutexLock ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    Mutex
    {- ^ /@mutex@/: a 'GI.GLib.Unions.Mutex.Mutex' -}
    -> m ()
mutexLock :: Mutex -> m ()
mutexLock mutex :: Mutex
mutex = IO () -> m ()
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
    Ptr Mutex
mutex' <- Mutex -> IO (Ptr Mutex)
forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
unsafeManagedPtrGetPtr Mutex
mutex
    Ptr Mutex -> IO ()
g_mutex_lock Ptr Mutex
mutex'
    Mutex -> IO ()
forall a. ManagedPtrNewtype a => a -> IO ()
touchManagedPtr Mutex
mutex
    () -> IO ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

#if ENABLE_OVERLOADING
data MutexLockMethodInfo
instance (signature ~ (m ()), MonadIO m) => O.MethodInfo MutexLockMethodInfo Mutex signature where
    overloadedMethod _ = mutexLock

#endif

-- method Mutex::trylock
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "mutex", argType = TInterface (Name {namespace = "GLib", name = "Mutex"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GMutex", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TBasicType TBoolean)
-- throws : False
-- Skip return : False

foreign import ccall "g_mutex_trylock" g_mutex_trylock :: 
    Ptr Mutex ->                            -- mutex : TInterface (Name {namespace = "GLib", name = "Mutex"})
    IO CInt

{- |
Tries to lock /@mutex@/. If /@mutex@/ is already locked by another thread,
it immediately returns 'False'. Otherwise it locks /@mutex@/ and returns
'True'.

'GI.GLib.Unions.Mutex.Mutex' is neither guaranteed to be recursive nor to be
non-recursive.  As such, calling 'GI.GLib.Unions.Mutex.mutexLock' on a 'GI.GLib.Unions.Mutex.Mutex' that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks or arbitrary return values).
-}
mutexTrylock ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    Mutex
    {- ^ /@mutex@/: a 'GI.GLib.Unions.Mutex.Mutex' -}
    -> m Bool
    {- ^ __Returns:__ 'True' if /@mutex@/ could be locked -}
mutexTrylock :: Mutex -> m Bool
mutexTrylock mutex :: Mutex
mutex = IO Bool -> m Bool
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO Bool -> m Bool) -> IO Bool -> m Bool
forall a b. (a -> b) -> a -> b
$ do
    Ptr Mutex
mutex' <- Mutex -> IO (Ptr Mutex)
forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
unsafeManagedPtrGetPtr Mutex
mutex
    CInt
result <- Ptr Mutex -> IO CInt
g_mutex_trylock Ptr Mutex
mutex'
    let result' :: Bool
result' = (CInt -> CInt -> Bool
forall a. Eq a => a -> a -> Bool
/= 0) CInt
result
    Mutex -> IO ()
forall a. ManagedPtrNewtype a => a -> IO ()
touchManagedPtr Mutex
mutex
    Bool -> IO Bool
forall (m :: * -> *) a. Monad m => a -> m a
return Bool
result'

#if ENABLE_OVERLOADING
data MutexTrylockMethodInfo
instance (signature ~ (m Bool), MonadIO m) => O.MethodInfo MutexTrylockMethodInfo Mutex signature where
    overloadedMethod _ = mutexTrylock

#endif

-- method Mutex::unlock
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "mutex", argType = TInterface (Name {namespace = "GLib", name = "Mutex"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GMutex", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_mutex_unlock" g_mutex_unlock :: 
    Ptr Mutex ->                            -- mutex : TInterface (Name {namespace = "GLib", name = "Mutex"})
    IO ()

{- |
Unlocks /@mutex@/. If another thread is blocked in a 'GI.GLib.Unions.Mutex.mutexLock'
call for /@mutex@/, it will become unblocked and can lock /@mutex@/ itself.

Calling 'GI.GLib.Unions.Mutex.mutexUnlock' on a mutex that is not locked by the
current thread leads to undefined behaviour.
-}
mutexUnlock ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    Mutex
    {- ^ /@mutex@/: a 'GI.GLib.Unions.Mutex.Mutex' -}
    -> m ()
mutexUnlock :: Mutex -> m ()
mutexUnlock mutex :: Mutex
mutex = IO () -> m ()
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
    Ptr Mutex
mutex' <- Mutex -> IO (Ptr Mutex)
forall a. (HasCallStack, ManagedPtrNewtype a) => a -> IO (Ptr a)
unsafeManagedPtrGetPtr Mutex
mutex
    Ptr Mutex -> IO ()
g_mutex_unlock Ptr Mutex
mutex'
    Mutex -> IO ()
forall a. ManagedPtrNewtype a => a -> IO ()
touchManagedPtr Mutex
mutex
    () -> IO ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

#if ENABLE_OVERLOADING
data MutexUnlockMethodInfo
instance (signature ~ (m ()), MonadIO m) => O.MethodInfo MutexUnlockMethodInfo Mutex signature where
    overloadedMethod _ = mutexUnlock

#endif

#if ENABLE_OVERLOADING
type family ResolveMutexMethod (t :: Symbol) (o :: *) :: * where
    ResolveMutexMethod "clear" o = MutexClearMethodInfo
    ResolveMutexMethod "init" o = MutexInitMethodInfo
    ResolveMutexMethod "lock" o = MutexLockMethodInfo
    ResolveMutexMethod "trylock" o = MutexTrylockMethodInfo
    ResolveMutexMethod "unlock" o = MutexUnlockMethodInfo
    ResolveMutexMethod l o = O.MethodResolutionFailed l o

instance (info ~ ResolveMutexMethod t Mutex, O.MethodInfo info Mutex p) => O.IsLabelProxy t (Mutex -> p) where
    fromLabelProxy _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)

#if MIN_VERSION_base(4,9,0)
instance (info ~ ResolveMutexMethod t Mutex, O.MethodInfo info Mutex p) => O.IsLabel t (Mutex -> p) where
#if MIN_VERSION_base(4,10,0)
    fromLabel = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#else
    fromLabel _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#endif
#endif

#endif