/*
 * (c) Copyright, Real-Time Innovations, 2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef osapi_rwLock_h
#define osapi_rwLock_h

#include "log/log_common.h"
#include "osapi/osapi_log.h"
#include "osapi/osapi_type.h"
#include "osapi/osapi_errorCode.h"

#if defined(RTI_VXWORKS)
  #include "osapi/osapi_vxVersions.h"
  #include <sys/time.h>
#elif defined(RTI_WIN32)
  #include <sys/timeb.h>
#elif defined(RTI_UNIX) || defined(RTI_LYNX) || defined(RTI_QNX) \
        || defined(RTI_INTIME)
  #if defined(RTI_LYNX) && !defined(RTI_LYNXOS_SE) && !defined(RTI_LYNX500)
    #include <time.h>
  #else
    #include <sys/time.h>
  #endif
#elif defined(RTI_INTY)
  #include <INTEGRITY.h>
#endif

#if defined(RTI_OSAPI_POSIX_RWLOCK_SUPPORTED)
  #include <pthread.h>
#endif

#include "osapi/osapi_ntptime.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @internal \defgroup RTIOsapiRWLockClass RTIOsapiRWLock
 * \ingroup RTIOsapiModule
 *
 * \brief OS independent encapsulation of a read or write lock, referenced by
 * rwlock. An rwlock allows concurrent access for read-only operations,
 * whereas write operations require exclusive access.  This means that multiple
 * threads can read the data in parallel but an exclusive lock is needed for
 * writing or modifying data
 */
struct RTIOsapiRWLock;

/** @internal \ingroup RTIOsapiRWLockClass
  @brief ctor
*/
extern RTIOsapiDllExport struct RTIOsapiRWLock *RTIOsapiRWLock_new(void);

/** @internal \ingroup RTIOsapiRWLockClass
  @brief dtor
*/
extern RTIOsapiDllExport void RTIOsapiRWLock_delete(
        struct RTIOsapiRWLock *self);

/** @internal
 * \ingroup RTIOsapiRWLockClass
 *
 * @brief The RTIOsapiRWLock_lockReadLock function applies a read lock to the
 * read or write lock referenced by rwlock. The calling thread acquires the read
 * lock once there are no writers holding the lock.
 * If blockDuration is specified and the lock cannot be acquired without waiting
 * for other threads to unlock the lock, this wait terminates when the specified
 * timeout expires.
 *
 * A thread may hold multiple concurrent read locks on rwlock (that is,
 * successfully call the RTIOsapiRWLock_lockReadLock() function n times). If so,
 * the thread must perform matching unlocks (that is,
 * successfully call the RTIOsapiRWLock_unlockReadLock() function n times).
 *
 * @param self the read or write lock we are using
 * @param blockDuration the timeout to wait for the lock to be available, NULL
 * if infinite block.
 *
 * @return on platforms where it can fail, a failure is reflected by a non-zero
 * return code.
 */
extern RTIOsapiDllExport RTIOsapiConcurrencyErrorCode
RTIOsapiRWLock_lockReadLock(
        struct RTIOsapiRWLock *self,
        const struct RTINtpTime *blockDuration);

/** @internal
 * \ingroup RTIOsapiRWLockClass
 *
 * @brief The RTIOsapiRWLock_unlock function releases a read lock object. The
 * behavior of this function is undefined when RTI_OSAPI_POSIX_RWLOCK_SUPPORTED
 * is defined and there are no readers holding the lock. When
 * RTI_OSAPI_POSIX_RWLOCK_SUPPORTED is not defined the function fails when no
 * readers are holding the lock.
 *
 * @param self the read lock we are using
 *
 * @return on platforms where it can fail, a failure is reflected by a non-zero
 * return code.
 */
extern RTIOsapiDllExport RTIOsapiConcurrencyErrorCode
RTIOsapiRWLock_unlockReadLock(struct RTIOsapiRWLock *self);

/** @internal
 * \ingroup RTIOsapiRWLockClass
 *
 * @brief The RTIOsapiRWLock_lockWriteLock function applies a write lock to the
 * read or write lock referenced by rwlock. The calling thread acquires the
 * write lock once no other thread (reader or writer) holds the read or write
 * lock rwlock. The writer lock is not reentrant.
 * If blockDuration is specified and the lock cannot be acquired without waiting
 * for other threads to unlock the lock, this wait terminates when the specified
 * timeout expires.
 *
 * @param self the read or write lock we are using
 * @param blockDuration the timeout to wait for the lock to be available, NULL
 * if infinite block.
 *
 * @return on platforms where it can fail, a failure is reflected by a non-zero
 * return code.
 */
extern RTIOsapiDllExport RTIOsapiConcurrencyErrorCode
RTIOsapiRWLock_lockWriteLock(
        struct RTIOsapiRWLock *self,
        const struct RTINtpTime *blockDuration);

/** @internal
 * \ingroup RTIOsapiRWLockClass
 *
 * @brief The RTIOsapiRWLock_unlock function releases a write lock object.
 * RTIOsapiRWLock_unlock fails when there are no writers holding the lock.
 *
 * @param self the write lock we are using
 *
 * @return on platforms where it can fail, a failure is reflected by a non-zero
 * return code.
 */
extern RTIOsapiDllExport RTIOsapiConcurrencyErrorCode
RTIOsapiRWLock_unlockWriteLock(struct RTIOsapiRWLock *self);


#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* osapi_rwLock_h */