lock.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file lock.h  
00005 *   @brief      A minimalistic platform agnostic lock abstraction for thread
00006 *               synchronization.
00007 *   @details    The Lock component is implemented in order to achieve thread
00008 *               synchronization, as we may have a requirement to consume locks
00009 *               across different platforms. This component exposes some generic
00010 *               APIs so that it can be extended for platform specific
00011 *               implementations.
00012 */
00013 
00014 #ifndef LOCK_H
00015 #define LOCK_H
00016 
00017 #include "azure_c_shared_utility/macro_utils.h"
00018 #include "azure_c_shared_utility/umock_c_prod.h"
00019 
00020 #ifdef __cplusplus
00021 extern "C" {
00022 #endif
00023 
00024 typedef void* LOCK_HANDLE;
00025 
00026 #define LOCK_RESULT_VALUES \
00027     LOCK_OK, \
00028     LOCK_ERROR \
00029 
00030 /** @brief Enumeration specifying the lock status.
00031 */
00032 DEFINE_ENUM(LOCK_RESULT, LOCK_RESULT_VALUES);
00033 
00034 /**
00035  * @brief   This API creates and returns a valid lock handle.
00036  *
00037  * @return  A valid @c LOCK_HANDLE when successful or @c NULL otherwise.
00038  */
00039 MOCKABLE_FUNCTION(, LOCK_HANDLE, Lock_Init);
00040 
00041 /**
00042  * @brief   Acquires a lock on the given lock handle. Uses platform
00043  *          specific mutex primitives in its implementation.
00044  *
00045  * @param   handle  A valid handle to the lock.
00046  *
00047  * @return  Returns @c LOCK_OK when a lock has been acquired and
00048  *          @c LOCK_ERROR when an error occurs.
00049  */
00050 MOCKABLE_FUNCTION(, LOCK_RESULT, Lock, LOCK_HANDLE, handle);
00051 
00052 /**
00053  * @brief   Releases the lock on the given lock handle. Uses platform
00054  *          specific mutex primitives in its implementation.
00055  *
00056  * @param   handle  A valid handle to the lock.
00057  *
00058  * @return  Returns @c LOCK_OK when the lock has been released and
00059  *          @c LOCK_ERROR when an error occurs.
00060  */
00061 MOCKABLE_FUNCTION(, LOCK_RESULT, Unlock, LOCK_HANDLE, handle);
00062 
00063 /**
00064  * @brief   The lock instance is destroyed.
00065  *
00066  * @param   handle  A valid handle to the lock.
00067  *
00068  * @return  Returns @c LOCK_OK when the lock object has been
00069  *          destroyed and @c LOCK_ERROR when an error occurs.
00070  */
00071 MOCKABLE_FUNCTION(, LOCK_RESULT, Lock_Deinit, LOCK_HANDLE, handle);
00072 
00073 #ifdef __cplusplus
00074 }
00075 #endif
00076 
00077 #endif /* LOCK_H */