source: azure_iot_hub/trunk/azure_iothub/c-utility/inc/azure_c_shared_utility/lock.h@ 389

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

/** @file lock.h  
*       @brief          A minimalistic platform agnostic lock abstraction for thread
*                               synchronization.
*       @details        The Lock component is implemented in order to achieve thread
*                               synchronization, as we may have a requirement to consume locks
*                               across different platforms. This component exposes some generic
*                               APIs so that it can be extended for platform specific
*                               implementations.
*/

#ifndef LOCK_H
#define LOCK_H

#include "azure_c_shared_utility/macro_utils.h"
#include "azure_c_shared_utility/umock_c_prod.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef void* LOCK_HANDLE;

#define LOCK_RESULT_VALUES \
    LOCK_OK, \
    LOCK_ERROR \

/** @brief Enumeration specifying the lock status.
*/
MU_DEFINE_ENUM(LOCK_RESULT, LOCK_RESULT_VALUES);

/**
 * @brief       This API creates and returns a valid lock handle.
 *
 * @return      A valid @c LOCK_HANDLE when successful or @c NULL otherwise.
 */
MOCKABLE_FUNCTION(, LOCK_HANDLE, Lock_Init);

/**
 * @brief       Acquires a lock on the given lock handle. Uses platform
 *                      specific mutex primitives in its implementation.
 *
 * @param       handle  A valid handle to the lock.
 *
 * @return      Returns @c LOCK_OK when a lock has been acquired and
 *                      @c LOCK_ERROR when an error occurs.
 */
MOCKABLE_FUNCTION(, LOCK_RESULT, Lock, LOCK_HANDLE, handle);

/**
 * @brief       Releases the lock on the given lock handle. Uses platform
 *                      specific mutex primitives in its implementation.
 *
 * @param       handle  A valid handle to the lock.
 *
 * @return      Returns @c LOCK_OK when the lock has been released and
 *                      @c LOCK_ERROR when an error occurs.
 */
MOCKABLE_FUNCTION(, LOCK_RESULT, Unlock, LOCK_HANDLE, handle);

/**
 * @brief       The lock instance is destroyed.
 *
 * @param       handle  A valid handle to the lock.
 *
 * @return      Returns @c LOCK_OK when the lock object has been
 *                      destroyed and @c LOCK_ERROR when an error occurs.
 */
MOCKABLE_FUNCTION(, LOCK_RESULT, Lock_Deinit, LOCK_HANDLE, handle);

#ifdef __cplusplus
}
#endif

#endif /* LOCK_H */