------------------------->  GNU Sather - sourcefile  <-------------------------
-- Copyright (C) 2000 by K Hopper, University of Waikato, New Zealand        --
-- This file is part of the GNU Sather library. It is free software; you may --
-- redistribute  and/or modify it under the terms of the GNU Library General --
-- Public  License (LGPL)  as published  by the  Free  Software  Foundation; --
-- either version 2 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 Doc/LGPL for more details.       --
-- The license text is also available from:  Free Software Foundation, Inc., --
-- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA                     --
-------------->  Please email comments to <bug-sather@gnu.org>  <--------------

abstract class $LOCK < $LOCK_MGR_ACCESS is

--        This abstract class is the primitive one from which all other lock
--   classes are necessarily derived.

--         Version 1.2 Nov 98.   Copyright K Hopper, U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       16 Apr 96        kh       Original for Sather 1.1 distrib
--        7 Apr 97        kh       Modified for style conformance
--       13 Nov 98        kh       Revised for 1.2 dist.


acquirable(
           tid : THREAD_ID
           ) : BOOL ;

--        This predicate returns true if and only if the lock may be acquired.
--   Note that this is non-atomic with any subsequent acquire call.


acquire(
        tid : THREAD_ID
        ) ;

--        This routine acquires the requested lock, being forced to wait if it
--   is not available.


release(
         tid : THREAD_ID
         ) ;

--        This routine releases the lock - which will enable any other waiting
--   thread to acquire it.


request(
        tid : THREAD_ID
        ) ;

--        This routine requests the lock.


cancel_request(
               tid : THREAD_ID
               ) ;

--        This routine cancels an outstanding request for the lock.


wait_for(
         tid : THREAD_ID
         ) ;

--        This routine returns when the lock has been obtained by the given
--   thread.


wait_for(
         tid : THREAD_ID
         ) : ARRAY{THREAD_ID} ;

--        This routine returns an array of those threads which are waiting for
--   the lock.


combinations : ARRAY{ARRAY{$LOCK}} ;

--        This routine returns an array consisting of the queues on each of
--   a group of locks.

combined_with(
              lcks : ARRAY{$LOCK},
              tids : ARRAY{THREAD_ID}
              ) ;

--        This routine associates a thread with a lock for each of the pairs
--   provided as arguments.

end ; -- $LOCK

-------------------------------------------------------------------------------

abstract class $ATTACH < $MUTEX, $ATTACH_SYNC is

--        This abstract class defines birth, death and synchronise as the only
--   common methods for attach classes.

--         Version 1.1 Apr 97.   Copyright K Hopper, U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       16 Apr 96        kh       Original for Sather 1.1 distrib
--        7 Apr 97        kh       Modified for style conformance

birth ;

--        This routine attaches the current thread to a cluster.


death ;

--        This routine remvoes the current thread from the cluster.


synchronize ;

--        This routine synchronizes the current thread and threads on other
--    clusters, blocking until corresponding imports/exports have been done.

end ; -- $ATTACH

------------------------------------------------------------------------------

abstract class $ATTACH{TYP} < $MUTEX, $ATTACH_SYNC is

--        This abstract class defines the common routines used in parameterised
--   attach classes.

--         Version 1.1 Apr 97.   Copyright K Hopper, U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       16 Apr 96        kh       Original for Sather 1.1 distrib
--        7 Apr 97        kh       Modified for style conformance

birth ;

--        This routine attaches the current thread to a cluster.


death(
     val : TYP
     ) ;

--        This routine remvoes the current thread from the cluster, returning
--   the given data value to its initiating thread.


synchronize ;

--        This routine synchronizes the current thread and threads on other
--    clusters, blocking until corresponding imports/exports have been done.

end ; -- $ATTACH{TYP}

-------------------------------------------------------------------------------

abstract class  $ATTACH_SYNC is

--        This abstract variant of ATTACH does not provide for death!  If this
--   is not available then synchronism is not possible from within external
--   service components.

--         Version 1.1 Apr 97.   Copyright K Hopper, U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       16 Apr 96        kh       Original for Sather 1.1 distrib
--        7 Apr 97        kh       Modified for style conformance

birth ;

--        This routine attaches the current thread to a cluster.


synchronize ;

--        This routine synchronizes the current thread and threads on other
--    clusters, blocking until corresponding imports/exports have been done.

end ; -- $ATTACH_SYNC

-------------------------------------------------------------------------------

immutable class LOCK_STATE < $ENUMS{LOCK_STATE} is

--        This class defines the kind of conditions used by both lock and mutex
--   classes.

--        The corresponding message file should contain appropriate names for
--   these in the local culture and environment.

--         Version 1.0 Nov 98.   Copyright K Hopper, U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       13 Nov 98        kh            Original from Sather 1.2 distrib.


include ENUM{LOCK_STATE} ;


private const val_count : CARD := 9 ;


--        The next routines provide the enumeration itself.

     Mutex : SAME is return enum(1) end ;
     Threads : SAME is return enum(2) end ;
     No_Threads : SAME is return enum(3) end ;
     Empty : SAME is return enum(4) end ;
     Not_Empty : SAME is return enum(5) end ;
     No_Value : SAME is return enum(6) end ;
     Has_Value : SAME is return enum(7) end ;
     Open : SAME is return enum(8) end ;
     Closed : SAME is return enum(9) end ;

end ; -- LOCK_STATE

-------------------------------------------------------------------------------

partial class LOCK_INCL is

--        This include class defines some of the common functionality of all
--   kinds of locks.   By including this in an implementing lock class those
--   routine which are not relevant to that class have - admittedly vacuous -
--   implementations.

--         Version 1.3 Feb 01.   Copyright K Hopper,  U of Waikato

--                          Development History
--                          -------------------

--        Date           Who By         Detail
--        ----           ------         ------

--       16 Apr 96        kh       Original for Sather 1.1 distrib
--        7 Apr 97        kh       Modified for style conformance
--       13 Nov 98        kh       Revised for 1.2.
--       26 Feb 01        kh       Made separate from LOCK_MGR_ACCESS


request(
        tid : THREAD_ID
        ) is

--        This routine is vacuous in this class.

end ;


cancel_request(
               tid : THREAD_ID
               ) is

--        This routine is also vacuous!

end ;


wait_for(
        tid : THREAD_ID
        ) is

--        This version of this routine does nothing.

end ;


wait_for(
            tid : THREAD_ID
            ) : ARRAY{THREAD_ID} is

--        This version of this routine merely returns void.

     return void
end ;


combinations : ARRAY{ARRAY{$LOCK}} is

--        This version of this routine also returns void.

     return void
end ;


combined_with(
             lcks  :ARRAY{$LOCK},
             tids : ARRAY{THREAD_ID}
             ) is

--        This version of this routine does nothing.

end ;


fast_lock(
          tid : THREAD_ID
          ) : BOOL is

--        This routine returns false -- meaning that no lock manager needs to
--   be involved.

     return false
end ;


fast_try(
         tid : THREAD_ID
         ) : CARD is

--        This version of this routine returns 0 meaning that a lock manager
--   is needed.

     return 0
end ;


fast_unlock(
           tid : THREAD_ID
           ) : BOOL is

--        This version of this routine returns true as an indication of success.

     return true
end ;

end ; -- LOCK_INCL

-------------------------------------------------------------------------------

immutable class PREFETCH is

--        This class is used internally to the compiler only and has no meaning
--   outside it.

end ; -- PREFETCH
