1------------------------------------------------------------------------------
2--                                                                          --
3--            FLORIST (FSU Implementation of POSIX.5) COMPONENTS            --
4--                                                                          --
5--                      P O S I X . S E M A P H O R E S                     --
6--                                                                          --
7--                                  S p e c                                 --
8--                                                                          --
9--             Copyright (C) 1996-1997 Florida State University             --
10--                     Copyright (C) 1998-2010, AdaCore                     --
11--                                                                          --
12--  This  file is a component  of FLORIST,  an implementation of the POSIX  --
13--  Ada  bindings  for  use with the GNAT Ada compiler and the FSU Gnu Ada  --
14--  Runtime Library (GNARL).                                                --
15--                                                                          --
16--  This package specification contains some text extracted from  IEEE STD  --
17--  1003.5: 1990, Information Technology -- POSIX Ada Language  Interfaces  --
18--  Part 1: Binding  for  System Application Program Interface, as amended  --
19--  by IEEE STD 1003.5b: 1996, Amendment 1: Realtime Extensions, copyright  --
20--  1996 by the Institute of Electrical and Electronics Engineers, Inc.     --
21--                                                                          --
22--  The package specifications in the IEEE standards cited above represent  --
23--  only a  portion  of  the  documents  and  are  not to be interpreteted  --
24--  outside the context  of  the documents.  The standards must be used in  --
25--  conjunction  with  the  package   specifications  in  order  to  claim  --
26--  conformance.   The IEEE takes no responsibility for and will assume no  --
27--  liability for damages resulting from the reader's misinterpretation of  --
28--  said  information resulting from its out-of-context nature.   To order  --
29--  copies of the IEEE standards,  please contact the  IEEE Service Center  --
30--  at 445 Hoes Lane, PO Box 1331, Piscataway, NJ 08855-1331; via phone at  --
31--  1-800-678-IEEE, 908-981-1393; or via fax at 908-981-9667.               --
32--                                                                          --
33--  These  package  specifications are  distributed in  the hope that they  --
34--  will  be useful, but  WITHOUT  ANY  WARRANTY; without even the implied  --
35--  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.        --
36--                                                                          --
37------------------------------------------------------------------------------
38
39with POSIX.C,
40     POSIX.IO,
41     POSIX.Permissions;
42package POSIX.Semaphores is
43
44   type Semaphore is limited private;
45   type Semaphore_Descriptor is private;
46   procedure Initialize
47     (Sem       : in out Semaphore;
48      Value     : Natural;
49      Is_Shared : Boolean := False);
50   function Descriptor_Of (Sem : Semaphore) return Semaphore_Descriptor;
51   procedure Finalize (Sem : in out Semaphore);
52   function Open
53     (Name           : POSIX.POSIX_String;
54      Masked_Signals : POSIX.Signal_Masking := POSIX.RTS_Signals)
55     return Semaphore_Descriptor;
56   function Open_Or_Create
57     (Name           : POSIX.POSIX_String;
58      Permissions    : POSIX.Permissions.Permission_Set;
59      Value          : Natural;
60      Options        : POSIX.IO.Open_Option_Set := POSIX.IO.Empty_Set;
61      Masked_Signals : POSIX.Signal_Masking := POSIX.RTS_Signals)
62     return Semaphore_Descriptor;
63   procedure Close (Sem : in out Semaphore_Descriptor);
64   procedure Unlink_Semaphore (Name : POSIX.POSIX_String);
65   procedure Wait
66     (Sem            : Semaphore_Descriptor;
67      Masked_Signals : POSIX.Signal_Masking := POSIX.RTS_Signals);
68   function Try_Wait (Sem : Semaphore_Descriptor) return Boolean;
69   procedure Post (Sem : Semaphore_Descriptor);
70   function Get_Value (Sem : Semaphore_Descriptor) return Integer;
71
72   --  .... Change POSIX.5b?
73   --  The Wait and Try_Wait operations are allowed to be interruptible
74   --  by a signal, according to the C binding.  Here, we have no
75   --  Masked_Signals parameter.  If the system support POSIX threads,
76   --  we are probably OK, since we will want to keep most signals masked,
77   --  in all threads but the corresponding handler (if any).
78
79private
80   --  We rely that type Semaphore will be passed by reference,
81   --  so that we can use 'Address of a parameter (even an "in" parameter)
82   --  to get a pointer to the actual object.
83   --  If there is any danger that it will not be passed by reference,
84   --  we will need to enclose the "sem_t" value as an aliased component of a
85   --  record or even of a tagged type.
86   type Dummy is tagged null record;
87   type Semaphore is record
88      Sem : aliased POSIX.C.sem_t;
89      --  to force by-reference parameter mode:
90      D : Dummy;
91   end record;
92   --  The "access constant" is sometimes a lie, but it allows
93   --  us to emulate the POSIX C-language interface without violating
94   --  Ada rules about pointers to variables vs. pointers to constants.
95   type Semaphore_Descriptor is access constant POSIX.C.sem_t;
96   pragma Convention (C, Semaphore_Descriptor);
97end POSIX.Semaphores;
98