Defines, Structures, Typedefs, Functions.
More...
|
| file | clHandleApi.h |
| | Header file of Handle Management related APIs.
|
| |
|
| ClRcT | clHandleCheckin (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle) |
| | Check in a handle. More...
|
| |
| ClRcT | clHandleCheckout (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle, CL_OUT void **instance) |
| | Check out a handle. More...
|
| |
| ClRcT | clHandleCreate (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClInt32T instanceSize, CL_OUT ClHandleT *handle) |
| | Creates a handle. More...
|
| |
| ClRcT | clHandleDatabaseCreate (CL_IN void(*destructor)(void *), CL_OUT ClHandleDatabaseHandleT *databaseHandle) |
| | Creates a handle database. More...
|
| |
| ClRcT | clHandleDatabaseDestroy (CL_IN ClHandleDatabaseHandleT databaseHandle) |
| | Destroys a handle database. More...
|
| |
| ClRcT | clHandleDestroy (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle) |
| | Destroy a handle. More...
|
| |
| ClWordT | clHandleGetDatabaseId (ClHandleDatabaseHandleT *databaseHandle) |
| | Get the handle database Identifier. More...
|
| |
| ClRcT | clHandleWithAddressCreate (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClInt32T instance_size, CL_IN ClIocPhysicalAddressT compAddr, CL_OUT ClHandleT *handle_out) |
| | Creates a handle with component address. More...
|
| |
Defines, Structures, Typedefs, Functions.
◆ clHandleCheckin()
Check in a handle.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
| handle | (in) The handle. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle database handle, or handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API signals the handle database the application is no longer modifying the data assoicated with the handle. Each call to this API negates the effect of exactly one call to the clHandleCheckout() API.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleCheckout()
Check out a handle.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
| handle | (in) The handle. |
| instance | (out) A pointer to return the pointer to the data. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle database handle, or handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API returns with a pointer that point to the data associated with the handle and increments the check-out counter of the handle. An application should call this function before making modifications to the handle data.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleCreate()
Creates a handle.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
| instanceSize | (in) Size of memory to be allocated. |
| handle | (out) Pointer to return the unique handle. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle database handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
| CL_ERR_NO_RESOURCE | The database is already marked for destroy (perhaps on another thread), so it is not allowed to create new handles. |
| CL_ERR_NO_MEMORY | Could not allocated memory for handle or data |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API creates a new handle, unique within the context of the given handle database. It also allocates memory of given size for data that the application can use to store any data associated with this handle.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleDatabaseCreate()
Creates a handle database.
- Header File
- clHandleApi.h
- Parameters
-
| destructor | (in) An optional pointer to a destructor function. Called when a handle is to be destroyed with its associated data. If the data is in one monolithic dynamically allocated block, the destructor is not needed. If the data has pointers pointing to separately allocated memory blocks, the destructrore should be provided and should be responsible to clean-up the auxiliary data. |
| databaseHandle | (out) A pointer to get a unique handle back that can be used in subsequent calls to the handle database. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_NO_MEMORY | Memory allocation failure. |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API creates and initializes a handle database.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleDatabaseDestroy()
Destroys a handle database.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API destroys and frees all data associated with a handle database.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleDestroy()
Destroy a handle.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
| handle | (in) The handle. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle database handle or handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API destroys (recycles) a given handle, releasing not only the handle, but also the data (memory) allocated in association with the handle. If a desructor function was provided at the time when the database was created, the destructor function is called before the handle data is freed.
If the handle is checked out by the application when this API is called, then the destruction of the handle will be delayed until no further checkouts are pending.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()
◆ clHandleGetDatabaseId()
Get the handle database Identifier.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
- Return values
-
- Description
- This API returns the Id associated with a handle database. This id is stored in every handle created in this database. However, note that this value will not ALWAYS correspond with a valid handle because you can store handles created in other nodes in a local handle database using the clHandleCreateSpecifiedHandle() API.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy(), clHandleCreateSpecifiedHandle()
◆ clHandleWithAddressCreate()
Creates a handle with component address.
- Header File
- clHandleApi.h
- Parameters
-
| databaseHandle | (in) The handle database handle. |
| instanceSize | (in) Size of memory to be allocated. |
| compAddr | (in) Component address to be included into the handle. |
| handle | (out) Pointer to return the unique handle. |
- Return values
-
| CL_OK | The API executed successfully, the returned handle is valid. |
| CL_ERR_INVALID_HANDLE | Invalid handle database handle. |
| CL_ERR_MUTEX_ERROR | Error in securing mutex on the database. |
| CL_ERR_NO_RESOURCE | The database is already marked for destroy (perhaps on another thread), so it is not allowed to create new handles. |
| CL_ERR_NO_MEMORY | Could not allocated memory for handle or data |
- Note
- Returned error is a combination of the component id and error code. Use
CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.
- Description
- This API creates a new handle, unique within the context of the given handle database. It also allocates memory of given size for data that the application can use to store any data associated with this handle.
- Library File
- ClUtil
- See also
- clHandleCreate, clHandleCheckout(), clHandleDestroy()