1 files changed, 84 insertions, 0 deletions
diff --git a/src/ssx/ssx/ssx_semaphore_init.c b/src/ssx/ssx/ssx_semaphore_init.c
new file mode 100755
index 0000000..98bba89
--- /dev/null
+++ b/src/ssx/ssx/ssx_semaphore_init.c
@@ -0,0 +1,84 @@
+// $Id: ssx_semaphore_init.c,v 1.2 2014/02/03 01:30:44 daviddu Exp $
+// $Source: /afs/awd/projects/eclipz/KnowledgeBase/.cvsroot/eclipz/chips/p8/working/procedures/ssx/ssx/ssx_semaphore_init.c,v $
+//-----------------------------------------------------------------------------
+// *! (C) Copyright International Business Machines Corp. 2013
+// *! All Rights Reserved -- Property of IBM
+// *! *** IBM Confidential ***
+//-----------------------------------------------------------------------------
+
+/// \file ssx_semaphore_init.c
+/// \brief SSX semaphore API initialization routines
+///
+/// The entry points in this file are routines that are typically used during
+/// initialization, and their code space could be deallocated and recovered if
+/// no longer needed by the application after initialization.
+
+#include "ssx.h"
+
+/// Create (initialize) a semaphore
+///
+/// \param semaphore A pointer to an SsxSemaphore structure to initialize
+///
+/// \param initial_count The initial count of the semaphore
+///
+/// \param max_count The maximum count allowed in the semaphore, for error
+/// checking 
+///
+/// Semaphores are created (initialized) by a call of \c
+/// ssx_semaphore_create(), using an application-provided instance of an \c
+/// SsxSemaphore structure.  This structure \e is the semaphore, so the
+/// application must never modify the structure if the semaphore is in use.
+/// SSX has no way to know if an \c SsxSemaphore structure provided to
+/// \c ssx_semaphore_create() is safe to use as a semaphore, and will silently
+/// modify whatever memory is provided.
+///
+/// SSX provides two simple overflow semantics based on the value of max_count
+/// in the call of \c ssx_semaphore_create().
+///
+/// If \a max_count = 0, then posting to the semaphore first increments the
+/// internal count by 1.  Overflows are ignored and will wrap the internal
+/// count through 0.
+///
+/// If \a max_count != 0, then posting to the semaphore first increments the
+/// internal count by 1, wrapping through 0 in the event of overflow. If the
+/// resulting count is greater than max_count, \c ssx_semaphore_post() will
+/// return the error \c -SSX_SEMAPHORE_POST_OVERFLOW to the caller.
+///
+/// In most applications it is probably best to use the \a max_count != 0
+/// semantics to trap programming errors, unless there is a specific
+/// application where overflow is expected and ignorable. As a fine point of
+/// the specification, a \a max_count of 0 is equivalent to a max_count of
+/// 0xFFFFFFFF.
+///
+/// Return values other then SSX_OK (0) are errors; see \ref ssx_errors
+///
+/// \retval 0 Successful completion
+///
+/// \retval -SSX_INVALID_SEMAPHORE_AT_CREATE The \a semaphore is a null (0) 
+/// pointer.
+/// 
+/// \retval -SSX_INVALID_ARGUMENT_SEMAPHORE The \a max_count is non-zero 
+/// and less than the \a initial_count.
+
+int
+ssx_semaphore_create(SsxSemaphore      *semaphore,
+                     SsxSemaphoreCount initial_count,
+                     SsxSemaphoreCount max_count)
+{
+    if (SSX_ERROR_CHECK_API) {
+        SSX_ERROR_IF(semaphore == 0, SSX_INVALID_SEMAPHORE_AT_CREATE);
+        SSX_ERROR_IF((max_count != 0) && (initial_count > max_count),
+                     SSX_INVALID_ARGUMENT_SEMAPHORE);
+    }
+
+    __ssx_thread_queue_clear(&(semaphore->pending_threads));
+    semaphore->count = initial_count;
+    semaphore->max_count = max_count;
+
+    return SSX_OK;
+}
+
+                             
+
+
+