Add documentation and non-blocking functions to fixed_queue.

Change-Id: Ia13166238847d6e1cebfda1bf5bdafd9ddc8b8e1

diff --git a/osi/include/fixed_queue.h b/osi/include/fixed_queue.h
index 5c4f9c4..da19c28 100644 (file)
--- a/osi/include/fixed_queue.h
+++ b/osi/include/fixed_queue.h
@@ -1,17 +1,58 @@
+/******************************************************************************
+ *
+ *  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 "list.h"
+#include <stdbool.h>
 
 struct fixed_queue_t;
 typedef struct fixed_queue_t fixed_queue_t;
 
 typedef void (*fixed_queue_free_cb)(void *data);
 
+// Creates a new fixed queue with the given |capacity|. If more elements than
+// |capacity| are added to the queue, the caller is blocked until space is
+// made available in the queue. Returns NULL on failure. The caller must free
+// the returned queue with |fixed_queue_free|.
 fixed_queue_t *fixed_queue_new(size_t capacity);
 
 // Freeing a queue that is currently in use (i.e. has waiters
-// blocked on it) resuls in undefined behaviour.
+// blocked on it) results in undefined behaviour.
 void fixed_queue_free(fixed_queue_t *queue, fixed_queue_free_cb free_cb);
 
+// Enqueues the given |data| into the |queue|. The caller will be blocked
+// if nore more space is available in the queue. Neither |queue| nor |data|
+// may be NULL.
 void fixed_queue_enqueue(fixed_queue_t *queue, void *data);
+
+// Dequeues the next element from |queue|. If the queue is currently empty,
+// this function will block the caller until an item is enqueued. This
+// function will never return NULL. |queue| may not be NULL.
 void *fixed_queue_dequeue(fixed_queue_t *queue);
+
+// Tries to enqueue |data| into the |queue|. This function will never block
+// the caller. If the queue capacity would be exceeded by adding one more
+// element, this function returns false immediately. Otherwise, this function
+// returns true. Neither |queue| nor |data| may be NULL.
+bool fixed_queue_try_enqueue(fixed_queue_t *queue, void *data);
+
+// Tries to dequeue an element from |queue|. This function will never block
+// the caller. If the queue is empty, this function returns NULL immediately.
+// Otherwise, the next element in the queue is returned. |queue| may not be
+// NULL.
+void *fixed_queue_try_dequeue(fixed_queue_t *queue);

diff --git a/osi/src/fixed_queue.c b/osi/src/fixed_queue.c
index 76cf603..c03c6ee 100644 (file)
--- a/osi/src/fixed_queue.c
+++ b/osi/src/fixed_queue.c
@@ -1,3 +1,21 @@
+/******************************************************************************
+ *
+ *  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.
+ *
+ ******************************************************************************/
+
 #include <assert.h>
 #include <pthread.h>
 #include <stdlib.h>
@@ -79,12 +97,41 @@ void fixed_queue_enqueue(fixed_queue_t *queue, void *data) {
 void *fixed_queue_dequeue(fixed_queue_t *queue) {
   assert(queue != NULL);
 
-  void *ret;
-
   semaphore_wait(queue->dequeue_sem);
 
   pthread_mutex_lock(&queue->lock);
-  ret = list_front(queue->list);
+  void *ret = list_front(queue->list);
+  list_remove(queue->list, ret);
+  pthread_mutex_unlock(&queue->lock);
+
+  semaphore_post(queue->enqueue_sem);
+
+  return ret;
+}
+
+bool fixed_queue_try_enqueue(fixed_queue_t *queue, void *data) {
+  assert(queue != NULL);
+  assert(data != NULL);
+
+  if (!semaphore_try_wait(queue->enqueue_sem))
+    return false;
+
+  pthread_mutex_lock(&queue->lock);
+  list_append(queue->list, data);
+  pthread_mutex_unlock(&queue->lock);
+
+  semaphore_post(queue->dequeue_sem);
+  return true;
+}
+
+void *fixed_queue_try_dequeue(fixed_queue_t *queue) {
+  assert(queue != NULL);
+
+  if (!semaphore_try_wait(queue->dequeue_sem))
+    return NULL;
+
+  pthread_mutex_lock(&queue->lock);
+  void *ret = list_front(queue->list);
   list_remove(queue->list, ret);
   pthread_mutex_unlock(&queue->lock);