src/OSD/OSD_Semaphore.cdl

   1 -- Created on: 1992-04-21
   2 -- Created by: Stephan GARNAUD (ARM)
   3 -- Copyright (c) 1992-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22
  23
  24
  25
  26 class Semaphore from OSD
  27
  28    ---Purpose: IPC Tools -Semaphores
  29    --          The semaphores are used to facilitate shared resources.
  30    --          This implementation provides a way to ensure mutual
  31    --          exclusion using 'Lock' and 'Free' primitives.
  32    --          The Lock is used to prevent access if it's not yet allowed.
  33    --          The Free validates the semaphores and if possible, frees process
  34    --          waiting for a common resource.
  35
  36    uses Protection, Error, AsciiString from TCollection
  37 raises ConstructionError,  OSDError, ProgramError
  38
  39
  40 is
  41   Create returns Semaphore;
  42     ---Purpose: Allocate room for semaphore name.
  43     --          This is to be used with 'Open'.
  44     --          so the process is a client.
  45     ---Level: Advanced
  46
  47   Create (Name : AsciiString) returns Semaphore
  48     ---Purpose: Instantiates Semaphore object with a name.
  49     --          The name is the only way provided to work with a common
  50     --          semaphore for different processes.
  51     --          Each process working with the same semaphore must use
  52     --          a common known access : the semaphore's NAME.
  53     --          Raises ConstructionError when the name contains characters
  54     --          not in range of ' '...'~'.
  55     --          This is for a server process.
  56     ---Level: Advanced
  57    raises ConstructionError;
  58
  59   Build (me : in out) is static;
  60     ---Purpose: Sets semaphore (physically) into memory
  61     ---Level: Advanced
  62
  63   Open (me : in out ; Name : AsciiString)
  64     ---Purpose: Opens (physically) a semaphore
  65     --          Raises ConstructionError when the name contains characters
  66     --          not in range of ' '...'~'.
  67     ---Level: Advanced
  68    raises ConstructionError is static;
  69
  70   GetCounter (me : in out) returns Integer is static;
  71     ---Purpose: Returns current value of the semaphore's counter.
  72     --          Raises ProgramError when the semaphore is not open.
  73     ---Level: Advanced
  74
  75   SetCounter (me : in out; Value : Integer) is static;
  76     ---Purpose: Sets the semaphore's counter to a specific value.
  77     --          Raises ProgramError when the semaphore is not open.
  78     ---Level: Advanced
  79
  80   Delete (me: out)
  81     ---Purpose: Removes the semaphore.
  82     --          This is used only by server process !
  83     --          Raise ProgramError if the semaphore is already deleted.
  84     ---Level: Advanced
  85     raises ProgramError is static;
  86
  87   Lock (me: out)
  88     ---Purpose: Makes current process waiting for access
  89     --          Raises ProgramError when the semaphore does't exist.
  90     ---Level: Advanced
  91     raises ProgramError is static;
  92
  93   Free (me: out)
  94     ---Purpose: Frees one access to a semaphore.
  95     --          Raises ProgramError when the semaphore does't exist.
  96     ---Level: Advanced
  97     raises ProgramError is static;
  98
  99   Restore (me : in out)
 100     ---Purpose: Resets semaphore counter to zero.
 101     --          Raises ProgramError when the semaphore does't exist.
 102     ---Level: Advanced
 103     raises ProgramError is static;
 104
 105  Failed (me) returns Boolean is static;
 106    ---Purpose: Returns TRUE if an error occurs
 107    ---Level: Advanced
 108
 109  Reset (me : in out) is static;
 110    ---Purpose: Resets error counter to zero
 111    ---Level: Advanced
 112
 113  Perror (me : in out)
 114    ---Purpose: Raises OSD_Error
 115    ---Level: Advanced
 116    raises OSDError is static;
 117
 118  Error (me) returns Integer is static;
 119    ---Purpose: Returns error number if 'Failed' is TRUE.
 120    ---Level: Advanced
 121
 122  fields
 123    myName : AsciiString;      -- The semaphore name
 124    myKey   : Integer;
 125    mySemId : Integer;     -- Internal identification of semaphore
 126    myError : Error;
 127 end Semaphore from OSD;
 128