Add documentation for semaphore and add a semaphore_try_wait function.

Change-Id: I5440744e4bf7192efc4c8d0205502aa4296a4f9f

diff --git a/osi/include/semaphore.h b/osi/include/semaphore.h
index 3c8b13a..60136ca 100644 (file)
--- a/osi/include/semaphore.h
+++ b/osi/include/semaphore.h
@@ -1,10 +1,45 @@
+/******************************************************************************
+ *
+ *  Copyright (C) 2014 Google, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at:
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
 #pragma once
 
+#include <stdbool.h>
+
 struct semaphore_t;
 typedef struct semaphore_t semaphore_t;
 
+// Creates a new semaphore with an initial value of |value|.
+// Returns NULL on failure. The returned object must be released
+// with |semaphore_free|.
 semaphore_t *semaphore_new(unsigned int value);
+
+// Frees a semaphore allocated with |semaphore_new|. |semaphore| may
+// be NULL.
 void semaphore_free(semaphore_t *semaphore);
 
+// Decrements the value of |semaphore|. If it is 0, this call blocks until
+// it becomes non-zero. |semaphore| may not be NULL.
 void semaphore_wait(semaphore_t *semaphore);
+
+// Tries to decrement the value of |semaphore|. Returns true if the value was
+// decremented, false if the value was 0. This function never blocks. |semaphore|
+// may not be NULL.
+bool semaphore_try_wait(semaphore_t *semaphore);
+
+// Increments the value of |semaphore|. |semaphore| may not be NULL.
 void semaphore_post(semaphore_t *semaphore);

diff --git a/osi/src/semaphore.c b/osi/src/semaphore.c
index a46c435..feb860b 100644 (file)
--- a/osi/src/semaphore.c
+++ b/osi/src/semaphore.c
@@ -1,7 +1,26 @@
+/******************************************************************************
+ *
+ *  Copyright (C) 2014 Google, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at:
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
 #define LOG_TAG "osi_semaphore"
 
 #include <assert.h>
 #include <errno.h>
+#include <fcntl.h>
 #include <string.h>
 #include <sys/eventfd.h>
 #include <utils/Log.h>
@@ -44,6 +63,29 @@ void semaphore_wait(semaphore_t *semaphore) {
     ALOGE("%s unable to wait on semaphore: %s", __func__, strerror(errno));
 }
 
+bool semaphore_try_wait(semaphore_t *semaphore) {
+  assert(semaphore != NULL);
+  assert(semaphore->fd != -1);
+
+  int flags = fcntl(semaphore->fd, F_GETFL);
+  if (flags == -1) {
+    ALOGE("%s unable to get flags for semaphore fd: %s", __func__, strerror(errno));
+    return false;
+  }
+  if (fcntl(semaphore->fd, F_SETFL, flags | O_NONBLOCK) == -1) {
+    ALOGE("%s unable to set O_NONBLOCK for semaphore fd: %s", __func__, strerror(errno));
+    return false;
+  }
+
+  eventfd_t value;
+  if (eventfd_read(semaphore->fd, &value) == -1)
+    return false;
+
+  if (fcntl(semaphore->fd, F_SETFL, flags) == -1)
+    ALOGE("%s unable to resetore flags for semaphore fd: %s", __func__, strerror(errno));
+  return true;
+}
+
 void semaphore_post(semaphore_t *semaphore) {
   assert(semaphore != NULL);
   assert(semaphore->fd != -1);