osi/include/semaphore.h

   1 /******************************************************************************
   2  *
   3  *  Copyright (C) 2014 Google, Inc.
   4  *
   5  *  Licensed under the Apache License, Version 2.0 (the "License");
   6  *  you may not use this file except in compliance with the License.
   7  *  You may obtain a copy of the License at:
   8  *
   9  *  http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  *
  17  ******************************************************************************/
  18
  19 #pragma once
  20
  21 #include <stdbool.h>
  22
  23 struct semaphore_t;
  24 typedef struct semaphore_t semaphore_t;
  25
  26 // Creates a new semaphore with an initial value of |value|.
  27 // Returns NULL on failure. The returned object must be released
  28 // with |semaphore_free|.
  29 semaphore_t *semaphore_new(unsigned int value);
  30
  31 // Frees a semaphore allocated with |semaphore_new|. |semaphore| may
  32 // be NULL.
  33 void semaphore_free(semaphore_t *semaphore);
  34
  35 // Decrements the value of |semaphore|. If it is 0, this call blocks until
  36 // it becomes non-zero. |semaphore| may not be NULL.
  37 void semaphore_wait(semaphore_t *semaphore);
  38
  39 // Tries to decrement the value of |semaphore|. Returns true if the value was
  40 // decremented, false if the value was 0. This function never blocks. |semaphore|
  41 // may not be NULL.
  42 bool semaphore_try_wait(semaphore_t *semaphore);
  43
  44 // Increments the value of |semaphore|. |semaphore| may not be NULL.
  45 void semaphore_post(semaphore_t *semaphore);
  46
  47 // Returns a file descriptor representing this semaphore. The caller may
  48 // only perform one operation on the file descriptor: select(2). If |select|
  49 // indicates the fd is readable, the caller may call |semaphore_wait|
  50 // without blocking. If select indicates the fd is writable, the caller may
  51 // call |semaphore_post| without blocking. Note that there may be a race
  52 // condition between calling |select| and |semaphore_wait| or |semaphore_post|
  53 // which results in blocking behaviour.
  54 //
  55 // The caller must not close the returned file descriptor. |semaphore| may not
  56 // be NULL.
  57 int semaphore_get_fd(const semaphore_t *semaphore);