1------------------------------------------------------------------------------
2--                                                                          --
3--            FLORIST (FSU Implementation of POSIX.5) COMPONENTS            --
4--                                                                          --
5--                         P O S I X . M U T E X E S                        --
6--                                                                          --
7--                                  S p e c                                 --
8--                                                                          --
9--                                                                          --
10--  This  file is a component  of FLORIST,  an implementation of the POSIX  --
11--  Ada  bindings  for  use with the GNAT Ada compiler and the FSU Gnu Ada  --
12--  Runtime Library (GNARL).                                                --
13--                                                                          --
14--  This package specification contains some text extracted from  IEEE STD  --
15--  1003.5: 1990, Information Technology -- POSIX Ada Language  Interfaces  --
16--  Part 1: Binding  for  System Application Program Interface, as amended  --
17--  by IEEE STD 1003.5b: 1996, Amendment 1: Realtime Extensions, copyright  --
18--  1996 by the Institute of Electrical and Electronics Engineers, Inc.     --
19--                                                                          --
20--  The package specifications in the IEEE standards cited above represent  --
21--  only a  portion  of  the  documents  and  are  not to be interpreteted  --
22--  outside the context  of  the documents.  The standards must be used in  --
23--  conjunction  with  the  package   specifications  in  order  to  claim  --
24--  conformance.   The IEEE takes no responsibility for and will assume no  --
25--  liability for damages resulting from the reader's misinterpretation of  --
26--  said  information resulting from its out-of-context nature.   To order  --
27--  copies of the IEEE standards,  please contact the  IEEE Service Center  --
28--  at 445 Hoes Lane, PO Box 1331, Piscataway, NJ 08855-1331; via phone at  --
29--  1-800-678-IEEE, 908-981-1393; or via fax at 908-981-9667.               --
30--                                                                          --
31--  These  package  specifications are  distributed in  the hope that they  --
32--  will  be useful, but  WITHOUT  ANY  WARRANTY; without even the implied  --
33--  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.        --
34--                                                                          --
35------------------------------------------------------------------------------
36
37with POSIX.C;
38package POSIX.Mutexes is
39
40   --  ==========  --
41   --   WARNINGS   --
42   --  ==========  --
43
44   --  This package is for mixed-language programming, in which
45   --  an Ada task needs to synchronize with a C thread.
46
47   --  Do NOT use POSIX mutexes to synchronize between Ada tasks.
48   --  Instead, use Ada protected objects.
49   --  Protected objects are implemented using mutexes.
50   --  The difference is that they are safer.
51   --  In particular protected operations are abort-deferred,
52   --  and have cleanup code to ensure mutexes are always released,
53   --  even if a protected operation completes abnormally due to an exception.
54   --  If you use one of these "raw" mutexes, you risk undefined
55   --  behavior if you violate any of the POSIX.1c rules about mutexes,
56   --  or if you attempt to abort (including ATC) a task that is performing
57   --  a mutex or CV operation.
58
59   type Mutex is limited private;
60   type Mutex_Descriptor is private;
61
62   type Attributes is private;
63   procedure Initialize (Attr : in out Attributes);
64   procedure Finalize (Attr : in out Attributes);
65
66   function Get_Process_Shared (Attr : Attributes)
67     return Boolean;
68   procedure Set_Process_Shared
69     (Attr      : in out Attributes;
70      Is_Shared : Boolean := False);
71
72   subtype Ceiling_Priority is Integer;
73   type Locking_Policy is range 0 .. 2;
74   No_Priority_Inheritance : constant Locking_Policy := 0;
75   Highest_Blocked_Task : constant Locking_Policy := 1;
76   Highest_Ceiling_Priority : constant Locking_Policy := 2;
77
78   procedure Set_Locking_Policy
79     (Attr    : in out Attributes;
80      Locking : Locking_Policy);
81   function Get_Locking_Policy
82     (Attr : Attributes)
83     return Locking_Policy;
84   procedure Set_Ceiling_Priority
85     (Attr        : in out Attributes;
86      New_Ceiling : Ceiling_Priority);
87   function Get_Ceiling_Priority (Attr : Attributes)
88     return Ceiling_Priority;
89
90   procedure Initialize
91     (M    : in out Mutex;
92      Attr : Attributes);
93   procedure Initialize (M : in out Mutex);
94   function Descriptor_Of (M : Mutex) return Mutex_Descriptor;
95   procedure Finalize (M : in out Mutex);
96
97   procedure Set_Ceiling_Priority
98     (M           : Mutex_Descriptor;
99      New_Ceiling : Ceiling_Priority;
100      Old_Ceiling : out Ceiling_Priority);
101   function Get_Ceiling_Priority (M : Mutex_Descriptor)
102     return Ceiling_Priority;
103
104   procedure Lock (M : Mutex_Descriptor);
105   function  Try_Lock (M : Mutex_Descriptor) return Boolean;
106   procedure Unlock (M : Mutex_Descriptor);
107
108private
109   type Dummy is tagged null record;
110   type Attributes is record
111      Attr : aliased POSIX.C.pthread_mutexattr_t;
112      --  to force by-reference parameter mode:
113      D : Dummy;
114   end record;
115   type Mutex is record
116      Mutex : aliased POSIX.C.pthread_mutex_t;
117      --  to force by-reference parameter mode:
118      D : Dummy;
119   end record;
120   --  The "access constant" is sometimes a lie, but it allows
121   --  us to emulate the POSIX C-language interface without violating
122   --  Ada rules about pointers to variables vs. pointers to constants.
123   type Mutex_Descriptor is access constant POSIX.C.pthread_mutex_t;
124   pragma Convention (C, Mutex_Descriptor);
125end POSIX.Mutexes;
126