From a591f19f686f4c7eb8ec96c673963978414dcba9 Mon Sep 17 00:00:00 2001 From: huangyuchen Date: Mon, 30 Jan 2023 17:43:21 +0800 Subject: [PATCH] Delete redundent doc and modify README to support the newly added guidelines documents. Issue:I6BTBV Test:NA Signed-off-by: huangyuchen Change-Id: I76974102a63985f4761326c67039fbf7ec461fe4 --- README.md | 133 +++++----------------- README_zh.md | 147 ++++++++---------------- docs/en/c-utils-guide.md | 237 --------------------------------------- 3 files changed, 76 insertions(+), 441 deletions(-) delete mode 100644 docs/en/c-utils-guide.md diff --git a/README.md b/README.md index b291124..d18a608 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,13 @@ The **commonlibrary/c_utils** repository provides the following commonly used ``` commonlibrary/c_utils -└─ base - ├── include # Header files of APIs open to other subsystems - ├── src # Source files - └── test # Test code +├─ base +│ ├── include # Header files of APIs open to other subsystems +│ ├── src # Source files +│ └── test # Test code +├─ Docs + ├── en # Documents in English + └── zh-cn # Documents in Chinese ``` ## Condition Suitable for standard system. @@ -36,115 +39,37 @@ Suitable for standard system. ``` ./build.sh --product-name rk3568 --build-target commonlibrary/c_utils/base:utilsbase ``` -## Coding Directions -### ashmem -``` -sptr ashmem = Ashmem::CreateAshmem(MEMORY_NAME.c_str(), MEMORY_SIZE); -if (ashmem != nullptr) { - bool ret = ashmem->MapAshmem(PROT_READ | PROT_WRITE); -} - -... - -// Do not forget to unmap & close ashmem at the end -ashmem->UnmapAshmem(); -ashmem->CloseAshmem(); -``` - -### parcel -``` -// Write data into parcel in some order at writing port -struct TestData { - bool booltest; - int8_t int8test; - int16_t int16test; - int32_t int32test; - uint8_t uint8test; - uint16_t uint16test; - uint32_t uint32test; -}; - -... - -Parcel parcel(nullptr); -struct TestData data = { true, -0x34, 0x5634, -0x12345678, 0x34, 0x5634, 0x12345678 }; -bool result = false; - -result = parcel.WriteBool(data.booltest); -if (!result) { - // Deal with writing failure -} - -result = parcel.WriteInt8(data.int8test); -if (!result) { - // Deal with writing failure -} - -result = parcel.WriteInt16(data.int16test); -if (!result) { - // Deal with writing failure -} -result = parcel.WriteInt32(data.int32test); -if (!result) { - // Deal with writing failure -} +### How to Add Dependency of c_utils +1. Open the corresponding BUILD.gn file of the related module. +2. Add dependency to the corresponding block as follows: +```gn -result = parcel.WriteUint8(data.uint8test); -if (!result) { - // Deal with writing failure -} +ohos_shared_library("xxxxx") { + ... -result = parcel.WriteUint16(data.uint16test); -if (!result) { - // Deal with writing failure -} + external_deps = [ + ... + # Dependency of shared library(Optional) + "c_utils:utils", + # Dependency of static library(Optional) + "c_utils:utilsbase", + ] -result = parcel.WriteUint32(data.uint32test); -if (!result) { - // Deal with writing failure + ... } ``` -``` -// Read data with the order writing in at reading port -bool readbool = parcel.ReadBool(); - -int8_t readint8 = parcel.ReadInt8(); - -int16_t readint16 = parcel.ReadInt16(); - -int32_t readint32 = parcel.ReadInt32(); - -uint8_t readuint8 = parcel.ReadUint8(); - -uint16_t readuint16 = parcel.ReadUint16(); +## Coding Directions -uint32_t readuint32 = parcel.ReadUint32(); -``` -### refbase -``` -class TestRefBase : public RefBase { -... -}; -... -sptr test(new TestRefBase()); -... -``` -### timer -``` -void TimeOutCallback() -{ - ... -} -... -Utils::Timer timer("test_timer"); -uint32_t ret = timer.Setup(); -timer.Register(TimeOutCallback, 1, true); -std::this_thread::sleep_for(std::chrono::milliseconds(15)); -timer.Shutdown(); -``` +### [Timer](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/en/c_utils_timer.md) +### [Thread Pool](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/en/c_utils_thread_pool.md) ## Changelog +**2023/01/31** +1. Add docs directory，provide development guidelines for main functionalities in c_utils. +2. Add comments in header files. +3. Modify README in which the guidelines can be accessed by links in section "Coding Directions". + **2022/10/10** 1. Move this repository from utils/native to commonlibrary/c_utils. 2. Switch component name from utils_base to c_utils. diff --git a/README_zh.md b/README_zh.md index 02a6cdb..f9d4f87 100644 --- a/README_zh.md +++ b/README_zh.md @@ -14,10 +14,13 @@ C++公共基础类库为标准系统提供了一些常用的C++开发工具类 ``` commonlibrary/c_utils -└─ base - ├── include # 对各子系统开放的接口头文件 - ├── src # 源文件 - └── test # 测试代码 +├─ base +│ ├── include # 对各子系统开放的接口头文件 +│ ├── src # 源文件 +│ └── test # 测试代码 +├─ Docs + ├── en # 英文文档 + └── zh-cn # 中文文档 ``` ## 约束 @@ -38,115 +41,59 @@ commonlibrary/c_utils ``` ./build.sh --product-name rk3568 --build-target commonlibrary/c_utils/base:utilsbase ``` -## 使用说明 -### ashmem -``` -sptr ashmem = Ashmem::CreateAshmem(MEMORY_NAME.c_str(), MEMORY_SIZE); -if (ashmem != nullptr) { - bool ret = ashmem->MapAshmem(PROT_READ | PROT_WRITE); -} - -... +### 如何依赖c_utils +1. 进入相关模块对应BUILD.gn文件 +2. 在该模块对应位置中的`external_deps`字段内添加依赖，如下： +```gn -// 当使用结束时不要忘记解映射和关闭ashmem -ashmem->UnmapAshmem(); -ashmem->CloseAshmem(); -``` - -### parcel -``` -// 写入端以某种顺序写入数据 -struct TestData { - bool booltest; - int8_t int8test; - int16_t int16test; - int32_t int32test; - uint8_t uint8test; - uint16_t uint16test; - uint32_t uint32test; -}; - -... - -Parcel parcel(nullptr); -struct TestData data = { true, -0x34, 0x5634, -0x12345678, 0x34, 0x5634, 0x12345678 }; -bool result = false; - -result = parcel.WriteBool(data.booltest); -if (!result) { - // 写失败处理 -} +ohos_shared_library("xxxxx") { + ... -result = parcel.WriteInt8(data.int8test); -if (!result) { - // 写失败处理 -} - -result = parcel.WriteInt16(data.int16test); -if (!result) { - // 写失败处理 -} - -result = parcel.WriteInt32(data.int32test); -if (!result) { - // 写失败处理 -} - -result = parcel.WriteUint8(data.uint8test); -if (!result) { - // 写失败处理 -} - -result = parcel.WriteUint16(data.uint16test); -if (!result) { - // 写失败处理 -} + external_deps = [ + ... + # 动态库依赖(可选) + "c_utils:utils", + # 静态库依赖(可选) + "c_utils:utilsbase", + ] -result = parcel.WriteUint32(data.uint32test); -if (!result) { - // 写失败处理 + ... } ``` -``` -// 接收端根据写入端写入顺序读取数据 -bool readbool = parcel.ReadBool(); -int8_t readint8 = parcel.ReadInt8(); +## 使用说明 -int16_t readint16 = parcel.ReadInt16(); +### [使用匿名共享内存](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-ashmem.md) +### [使用智能指针管理动态分配内存对象](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-refbase.md) +### [使用Parcel作为数据容器](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-parcel.md) +### [定时器](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c_utils_timer.md) -int32_t readint32 = parcel.ReadInt32(); +### [读写锁](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-rwlock.md) +### [增强信号量功能](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-semaphore.md) +### [强化线程能力](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-thread.md) +### [线程池](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c_utils_thread_pool.md) -uint8_t readuint8 = parcel.ReadUint8(); -uint16_t readuint16 = parcel.ReadUint16(); +### [线程安全Map](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-safeMap.md) +### [有序Vector](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-sortedVector.md) +### [线程安全阻塞队列](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-safe_block_queue.md) +### [线程安全栈与队列](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-safe_queue.md) -uint32_t readuint32 = parcel.ReadUint32(); -``` -### refbase -``` -class TestRefBase : public RefBase { -... -}; -... -sptr test(new TestRefBase()); -... -``` -### timer -``` -void TimeOutCallback() -{ - ... -} -... -Utils::Timer timer("test_timer"); -uint32_t ret = timer.Setup(); -timer.Register(TimeOutCallback, 1, true); -std::this_thread::sleep_for(std::chrono::milliseconds(15)); -timer.Shutdown(); -``` +### [单例模式](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-singleton.md) +### [观察者模式](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-observer.md) + +### [日期与时间](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-datetime.md) +### [文件与目录](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-directory.md) +### [字符串处理](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-string.md) +### [读写文件](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-file.md) +### [管理、传递文件描述符](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide-uniquefd.md) ## Changelog +**2023/01/31** +1. 添加docs目录，提供c_utils内各主要功能的开发指导文档。 +2. 在源码头文件中添加注释。 +3. 修改Readme文档，开发指导文档可通过Readme中的"使用说明"章节跳转查看。 + **2022/10/10** 1. 路径变更。由utils/native移动至commonlibrary/c_utils； 2. 部件名变更。由utils_base变更为c_utils； diff --git a/docs/en/c-utils-guide.md b/docs/en/c-utils-guide.md deleted file mode 100644 index b6d0976..0000000 --- a/docs/en/c-utils-guide.md +++ /dev/null @@ -1,237 +0,0 @@ -# Developement Guidelines for c_utils - -## Overview - -### Introduction - -The commonlibrary/c_utils repository provides the following commonly used C++ utility classes for standard system: - -* Enhanced APIs for operations related to files, paths, and strings. -* APIs related to the read-write lock, semaphore, timer, thread, and thread pool. -* APIs related to the security data container and data serialization. -* Error codes for each subsystem. - -## Use Smart-Pointer to manag dynamically allocated object - -### Overview - -#### Introduction - -Smart Pointer are pointer-like classes. They simulates a pointer while providing added features, such as automatic memory management. - -* Automatic memory management is mainly about deallocating the related memory at the correct time when an object beyonds its life cycle. -* There are two different references for a single object. Strong Reference holds a pointer directly pointing to the object. Objects which are strong referenced ought to be alive/existed as long as these strong references exists, thus the references are still valid; Weak Reference holds a pointer indirectly pointing to the object. Objects which are weak referenced are not guaranteed to be alive/existed even if their weak references exist. - -> Notice: Descriptions above are valid only when smart pointers are properly used. - -#### Principle - -* Via reference counts, Smart-Pointer achieves auto-management of memory for the object pointed by it. Every object which can be managed holds a reference counter. The counter will destroy the object through a callback method when related counts reach 0. - -* Reference counter records two kinds of counts of references to the corresponded RefBase object, and a count of reference to the RefCounter itself. - -### Related Interfaces -#### OHOS::sptr - -Strong reference smart pointer to a RefBase(or its subclass) object. - -##### Detailed Description - -```cpp -template -``` - -Strong reference smart pointer to a RefBase(or its subclass) object. -**Template Parameters**: - -* **T** Specific class type managed by sptr. This class must inherit from RefBase. - -Directly reference the RefBase object. - -`#include ` - -##### Public Functions - -| Return Type | Name | -| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| | **sptr**() | -| template
| **sptr**(const sptr< O > & other)
Copy Constructor for sptr with different managed class type(O) | -| | **sptr**(const sptr< T > & other)
Copy Constructor for sptr with different managed class type(T) | -| | **sptr**(sptr< T > && other)
Move constructor. | -| | **sptr**(T * other)
Constructor with specified object to be managed. | -| | **sptr**(WeakRefCounter * p, bool force)
Constructor only used in promote process of wptr. | -| | **~sptr**() | -| void | **clear**()
Remove the reference to the managed object held by current sptr. | -| void | **ForceSetRefPtr**(T * other)
Set the pointer to the managed object. | -| T * | **GetRefPtr**() const
Get the pointer to the managed object. | -| | **operator T***() const
Type conversion operator. | -| bool | **operator!**() const
Logical-NOT operator. Check if sptr is a "null sptr". | -| bool | **operator!=**(const sptr< T > & other) const
Not-equal-to operator between sptrs. | -| bool | **operator!=**(const T * other) const
Not-equal-to operator between sptr and a raw pointer. | -| bool | **operator!=**(const wptr< T > & other) const
Not-equal-to operator between sptr and a wptr. | -| T & | **operator***() const
Dereference operator. It will return the object managed by this sptr. | -| T * | **operator->**() const
Member selection operator. It will return the specified member of the object managed by this sptr. | -| template
sptr< T > & | **operator=**(const sptr< O > & other)
Copy assignment operator for sptr with different managed class type(O) | -| sptr< T > & | **operator=**(const sptr< T > & other)
Copy assignment operator for sptr with same managed class type(T) | -| sptr< T > & | **operator=**(const wptr< T > & other)
Copy assignment operator for wptr with same managed class type(T) | -| sptr< T > & | **operator=**(sptr< T > && other)
Move assignment operator. | -| sptr< T > & | **operator=**(T * other)
Copy assignment operator with specified object to be managed. | -| bool | **operator==**(const sptr< T > & other) const
Equal-to operator between sptrs. | -| bool | **operator==**(const T * other) const
Equal-to operator between sptr and a raw pointer. | -| bool | **operator==**(const wptr< T > & other) const
Equal-to operator between sptr and a wptr. | - -#### OHOS::wptr - -Weak reference smart pointer to a RefBase(or its subclass) object. - -##### Detailed Description - -```cpp -template -``` - -Weak reference smart pointer to a RefBase(or its subclass) object. - -**Template Parameters**: - -* **T** Specific class type managed by wptr. This class must inherit from RefBase. - -It indirectly references the RefBase object, and directly references the WeakRefCounter object. - -`#include ` - -##### Public Functions - -| Return Type | Name | -| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| | **wptr**() | -| template
| **wptr**(const sptr< O > & other)
Copy constructor for sptr with different managed class type(O) | -| | **wptr**(const sptr< T > & other)
Copy constructor for sptr with same managed class type(T) | -| template
| **wptr**(const wptr< O > & other)
Copy constructor for wptr with different managed class type(O) | -| | **wptr**(const wptr< T > & other)
Copy constructor for wptr with same managed class type(T) | -| | **wptr**(T * other)
Constructor with specified object to be managed. | -| | **~wptr**() | -| bool | **AttemptIncStrongRef**(const void * objectId) const
Attempt to increment the strong reference count of the managed object. | -| T * | **GetRefPtr**() const
Get the pointer to the RefBase object. | -| bool | **operator!=**(const sptr< T > & other) const
Not-Equal-to operator between wptr and a input sptr object. | -| bool | **operator!=**(const T * other) const
Not-equal-to operator between wptr and a raw pointer. | -| bool | **operator!=**(const wptr< T > & other) const
Not-equal-to operator between two wptrs. | -| T & | **operator***() const
Dereference operator. It will return the object managed by this wptr. | -| T * | **operator->**() const
Member selection operator. It will return the specified member of the object managed by this wptr. | -| template
wptr< T > & | **operator=**(const sptr< O > & other)
Copy assignment operator for sptr with different managed class type(O) | -| wptr< T > & | **operator=**(const sptr< T > & other)
Copy assignment operator for sptr with same managed class type(T) | -| template
wptr< T > & | **operator=**(const wptr< O > & other)
Copy assignment operator for wptr with different managed class type(O) | -| wptr< T > & | **operator=**(const wptr< T > & other)
Copy assignment operator for wptr with same managed class type(T) | -| template
wptr< T > & | **operator=**(O * other)
Copy assignment operator with specified object to be managed. | -| wptr< T > & | **operator=**(T * other)
Copy assignment operator with specified object to be managed. | -| bool | **operator==**(const sptr< T > & other) const
Equal-to operator between wptr and a input sptr object. | -| bool | **operator==**(const T * other) const
Equal-to operator between wptr and a raw pointer. | -| bool | **operator==**(const wptr< T > & other) const
Equal-to operator between two wptrs. | -| const sptr< T > | **promote**() const
Promote a wptr to an sptr. | - -### Example - -1. Include the Header File - -```c++ -#include "refbase.h" -``` - -2. Usages -2.1 Definition of Example Target Class -```c++ -class RefBaseTest : RefBase -{ - virtual void show() - { - cout<<"Show RefBaseTest"< newSptr(new RefBaseTest); -wptr newWptr(new RefBaseTest); - -newSptr = new RefBaseTest(); -newWptr = new RefBaseTest(); - -sptr anotherSptr(new RefBaseTest); -wptr anotherWptr(new RefBaseTest); -sptr curSptr(anotherSptr); -wptr curWptr(anotherWptr); - -newSptr = anotherSptr; -newWptr = anotherWptr; - -Sptr subSptr(new SubRefBaseTest()); -Wptr subWptr(new SubRefBaseTest()); -curSptr = subSptr; -curWptr = subWptr; -// or -Sptr superSptr(subSptr); -Wptr superSptr(subWptr); - -curSptr->show(); -curWptr->show(); - -(*curSptr).show(); -(*curSptr).show(); -``` - -2.3 Special Usages - -```c++ - -sptr scurSptr(new RefBaseTest); -wptr scurWptr(new RefBaseTest); - -wptr snewWptr(scurSptr); -sptr snewSptr(scurWptr); -// or -sptr soldSptr(new RefBaseTest); -wptr soldWptr(new RefBaseTest); -soldSptr = scurWptr; // Original reference will be eliminated -soldWptr = scurSptr; - -// wptr -> sptr -sptr spromotedWptr = snewWptr.promote(); // Original weak reference still exists -``` - -### FAQ - -1. **Avoid using it combined with raw pointer and smart pointer(std::shared_ptr, etc.) in `std` simultaneously** - - * It will cause conflict in management，and thus undefined behavior. - * Using smart pointer to manage a valid raw pointer is not recommended. - -```c++ -RefBase* a = new RefBase(); -sptr s = a; -// or -sptr s(a); // raw pointer is easily mistakenly deleted -``` - -2. **Smart pointer should be constructed on the stack，object to be managed should on the heap(dynamically allocated)** - - * Smart pointer on the heap doesn't conform with the definition. - * Object on the stack will be destroyed automatically, which makes the object bypass the management from smart pointer. - -3. **Smart point is not ThreadSafe** - -4. **Avoid constructing smart pointer via implicit conversion** - - * Easily mislead other developers. - * Depend on specific compiler, exact behaviors can not be guaranteed. -- Gitee