service/native/common_library/client/include/native_service/cl_lock.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef _cl_lock_h_  // NOLINT(build/header_guard)
  17 #define _cl_lock_h_  // NOLINT(build/header_guard)
  18
  19 #include <stdint.h>
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * @file cl_lock.h
  27  * @brief \~english This file contains the base api of cl_clock.
  28  */
  29
  30 /** @addtogroup BaseSystem
  31  *  @{
  32  */
  33 /** @addtogroup native_service
  34  *  @ingroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup common_library
  38  *  @ingroup native_service
  39  *  @{
  40  */
  41
  42 ////////////////////////////////////////////////////////////////////////////////////
  43 /// \ingroup CL_LockSystemInit
  44 /// \~english @par Brief
  45 ///        Initialize the system lock.
  46 /// \~english @retval 0  Success
  47 /// \~english @retval -1 Error
  48 /// \~english @par Prerequisite
  49 ///        - Prerequisites are nothing.
  50 /// \~english @par Change of internal state
  51 ///        - Change of internal state according to the API does not occur.
  52 /// \~english @par Conditions of processing failure
  53 ///        - On system call shm_open error, -1 is returned.
  54 ///        - On system call ftrancate error, -1 is returned.
  55 ///        - On system call mmap error, -1 is returned.
  56 ///        - On system call pthread_mutexattr_setpshared error, -1 is returned.
  57 /// \~english @par Detail
  58 ///        This function will generate the Lock file, and initialize all the pthread_mutex_t slots.\n
  59 ///        This function must to be called in the system once, which is recommended on the SystemManager start.\n
  60 /// \~english @par
  61 ///        Lock file is formed with lots of slots. Every slot occupies 4KB.
  62 ///        The slot layout is:
  63 ///        0     ~ 4Byte  : field of PID
  64 ///        4Byte ~ 28Byte : field of pthread_mutex_t
  65 /// \~english @par Classification
  66 ///        Public
  67 /// \~english @par Type
  68 ///        Sync only
  69 /// \~english @see
  70 ///        none
  71 ////////////////////////////////////////////////////////////////////////////////////
  72 int32_t CL_LockSystemInit(void);  // NOLINT(readability/nolint)
  73
  74 ////////////////////////////////////////////////////////////////////////////////////
  75 /// \ingroup CL_LockProcessInit
  76 /// \~english @par Brief
  77 ///        Initialize the process Lock file.
  78 /// \~english @retval 0  Success
  79 /// \~english @retval -1 Error
  80 /// \~english @par Prerequisite
  81 ///        Should call CL_LockSystemInit() to generate Lock file.
  82 /// \~english @par Change of internal state
  83 ///        - Change of internal state according to the API does not occur.
  84 /// \~english @par Conditions of processing failure
  85 ///        - On system call shm_open error, -1 is returned.
  86 /// \~english @par Detail
  87 ///        Open the Lock file.\n
  88 ///        If process want to use the Lock, this function should be called.\n
  89 ///        It is recommended that this function should be called since start main function.
  90 /// \~english @par Classification
  91 ///        Public
  92 /// \~english @par Type
  93 ///        Sync only
  94 /// \~english @see
  95 ///        none
  96 ////////////////////////////////////////////////////////////////////////////////////
  97 int32_t CL_LockProcessInit(void);  // NOLINT(readability/nolint)
  98
  99 ////////////////////////////////////////////////////////////////////////////////////
 100 /// \ingroup CL_LockMap
 101 /// \~english @par Brief
 102 ///        Mapping the Lock information address.
 103 /// \~english @param [in] lid
 104 ///        int32_t - LockID of the Lock used.(0~LID_NUM) \n
 105 /// \~english @retval addr Lock address
 106 /// \~english @retval MAP_FAILED Error (errno)
 107 /// \~english @par Prerequisite
 108 ///        Should call CL_LockSystemInit(), CL_LockProcessInit() to open the Lock file.
 109 /// \~english @par Change of internal state
 110 ///        - Change of internal state according to the API does not occur.
 111 /// \~english @par Conditions of processing failure
 112 ///        - If LockID(lid) < 0, errno is set as EINVAL, and MAP_FAILED is returned
 113 ///        - If LockID(lid) > LID_NUM, errno is set as EINVAL, and MAP_FAILED is returned
 114 ///        - If systemcall mmap is failure, errno is set euqal with the errno of mmap, and MAP_FAILED is returned
 115 /// \~english @par Detail
 116 ///        Mapping the Lock information to the memory.\n
 117 ///        The related LockID should be assigned, when apply the share memory.\n
 118 /// \~english @par Classification
 119 ///        Public
 120 /// \~english @par Type
 121 ///        Sync only
 122 /// \~english @see
 123 ///        CL_LockUnmap
 124 ////////////////////////////////////////////////////////////////////////////////////
 125 void *CL_LockMap(int32_t lid);  // NOLINT(readability/nolint)
 126
 127 ////////////////////////////////////////////////////////////////////////////////////
 128 /// \ingroup CL_LockUnmap
 129 /// \~english @par Brief
 130 ///        Unmapping the Lock information.
 131 /// \~english @param [in] addr
 132 ///        void* - Lock information address.
 133 /// \~english @retval 0  Success
 134 /// \~english @retval -1 Error
 135 /// \~english @par Prerequisite
 136 ///        Should call CL_LockSystemInit(), CL_LockProcessInit() before this function is called
 137 /// \~english @par Change of internal state
 138 ///        - Change of internal state according to the API does not occur.
 139 /// \~english @par Conditions of processing failure
 140 ///        - If systemcall munmap is failure, errno is set euqal with the errno of munmap, -1 is returned
 141 /// \~english @par Detail
 142 ///        0 would be returned, even if not get the Lock.
 143 ///        The addr is the Lock information address that acquired from CL_LockMap.
 144 /// \~english @par Classification
 145 ///        Public
 146 /// \~english @par Type
 147 ///        Sync only
 148 /// \~english @see
 149 ///        CL_LockMap
 150 ////////////////////////////////////////////////////////////////////////////////////
 151 int32_t CL_LockUnmap(void *addr);  // NOLINT(readability/nolint)
 152
 153 ////////////////////////////////////////////////////////////////////////////////////
 154 /// \ingroup CL_LockGet
 155 /// \~english @par Brief
 156 ///        Get the Lock. Block until get the Lock.
 157 /// \~english @param [in] addr
 158 ///        void* - Lock information address.
 159 /// \~english @retval 0       Success
 160 /// \~english @retval EINVAL  Invalid parameter
 161 /// \~english @retval EDEADLK Mutex already locked
 162 /// \~english @par Prerequisite
 163 ///        Should call CL_LockMap to get the Lock information address.
 164 /// \~english @par Change of internal state
 165 ///        - Change of internal state according to the API does not occur.
 166 /// \~english @par Conditions of processing failure
 167 ///        - EINVAL as the parameter of Lock information address is NULL
 168 ///        - EINVAL as the parameter of Lock information address is MAP_FAILED
 169 ///        - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_lock failure.
 170 ///        - EDEADLK as the current thread already owns the mutex in the systemcall pthread_mutex_lock failure.
 171 /// \~english @par Detail
 172 ///        Get the Lock until other threads release it.
 173 ///        It will be deadlock if the current thread already owns the mutex.
 174 ///        The addr is the Lock information address that should be acquired from CL_LockMap.
 175 /// \~english @par Classification
 176 ///        Public
 177 /// \~english @par Type
 178 ///        Sync only
 179 /// \~english @see
 180 ///        CL_LockRelease
 181 ////////////////////////////////////////////////////////////////////////////////////
 182 int32_t CL_LockGet(void *addr);  // NOLINT(readability/nolint)
 183
 184 ////////////////////////////////////////////////////////////////////////////////////
 185 /// \ingroup CL_LockNowait
 186 /// \~english @par Brief
 187 ///        Try to get Lock, shall immediately return.
 188 /// \~english @param [in] addr
 189 ///        void* - Lock information address.
 190 /// \~english @retval 0       Success
 191 /// \~english @retval EINVAL  Invalid parameter
 192 /// \~english @retval EBUSY   Busy
 193 /// \~english @par Prerequisite
 194 ///        Should call CL_LockMap to get the Lock information address.
 195 /// \~english @par Change of internal state
 196 ///        - Change of internal state according to the API does not occur.
 197 /// \~english @par Conditions of processing failure
 198 ///        - EINVAL as input parameter addr, the Lock information address is NULL
 199 ///        - EINVAL as input parameter addr, the Lock information address if MAP_FAILED
 200 ///        - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_trylock failure.
 201 ///        - EBUSY as the mutex could not be acquired as it was already locked in the
 202 ///          systemcall pthread_mutex_trylock failure.
 203 /// \~english @par Detail
 204 ///        The addr is the Lock information address that should be acquired from CL_LockMap.
 205 ///        Get the Lock information from the pointed share memory.
 206 ///        Shall immediately return while not acquire the Lock.
 207 /// \~english @par Classification
 208 ///        Public
 209 /// \~english @par Type
 210 ///        Sync only
 211 /// \~english @see
 212 ///        CL_LockRelease
 213 ////////////////////////////////////////////////////////////////////////////////////
 214 int32_t CL_LockNowait(void *addr);  // NOLINT(readability/nolint)
 215
 216 ////////////////////////////////////////////////////////////////////////////////////
 217 /// \ingroup CL_LockRelease
 218 /// \~english @par Brief
 219 ///        Release the Lock.
 220 /// \~english @param [in] addr
 221 ///        addr   - Lock information address.
 222 /// \~english @retval 0       Success
 223 /// \~english @retval EINVAL  Invalid parameter
 224 /// \~english @retval EPERM   The current thread does not own the mutex
 225 /// \~english @par Prerequisite
 226 ///        - Should call CL_LockMap to get the Lock information address.
 227 /// \~english @par Change of internal state
 228 ///        - Change of internal state according to the API does not occur.
 229 /// \~english @par Conditions of processing failure
 230 ///        - EINVAL as input parameter addr, the Lock information address is NULL
 231 ///        - EINVAL as input parameter addr, the Lock information address if MAP_FAILED
 232 ///        - EINVAL as the mutex does not be initialized in the systemcall pthread_mutex_unlock failure.
 233 ///        - EPERM as the current thread does not own the mutex in the systemcall pthread_mutex_unlock failure.
 234 /// \~english @par Detail
 235 ///        0 would be returned, even if not get the Lock.
 236 ///        The addr is the Lock information address that should be acquired from CL_LockMap.
 237 ///        Release the Lock related with the share memory.
 238 /// \~english @par Classification
 239 ///        Public
 240 /// \~english @par Type
 241 ///        Sync only
 242 /// \~english @see
 243 ///        CL_LockGet, CL_LockNowait
 244 ////////////////////////////////////////////////////////////////////////////////////
 245 int CL_LockRelease(void *addr);  // NOLINT(readability/nolint)
 246
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251
 252 /** @}*/  // end of common_library
 253 /** @}*/  // end of NativeService
 254 /** @}*/  // end of BaseSystem
 255 #define LOCK_POS_MTX_RSV          40
 256 #define LOCK_HRDS_RSV             15
 257 #define LOCK_NSLOG_ACCES_IF_RSV   50
 258 #define LID_NUM                  140
 259 #endif  // #ifndef _cl_lock_h_  // NOLINT(build/header_guard)