1# 使用匿名共享内存(Ashmem, Anonymous Shared Memory)
2
3## 概述
4
5使用linux内核提供的驱动`dev/ashmem`，申请内核空间中的一块内存区域并映射至用户空间。利用其共享机制，可以实现较大数据量的进程间通信。
6
7## 涉及功能
8### OHOS::Ashmem
9
10C++公共基础库中的Ashmem实现，用于操作匿名共享内存(Ashmem)。
11
12#### 具体描述
13
14```cpp
15class OHOS::Ashmem;
16```
17具体操作包括创建并映射一块ashmem内存区域并对其进行读写等。
18**提示**: 尽管被智能指针管理，Ashmem对象仍需手动解除映射并关闭。
19
20
21`#include <ashmem.h>`
22
23继承自 OHOS::RefBase
24
25#### Public Functions
26
27| 返回类型       | 名称           |
28| -------------- | -------------- |
29| sptr< Ashmem > | **CreateAshmem**(const char* name, int32_t size)<br>使用指定名称及大小创建Ashmem对象。  |
30| | **Ashmem**(int fd, int32_t size)<br>构造Ashmem对象。  |
31| | **~Ashmem**() override |
32| void | **CloseAshmem**()<br>通过文件描述符关闭当前ashmem。  |
33| int | **GetAshmemFd**() const<br>获取内核中对应ashmem的文件描述符。  |
34| int32_t | **GetAshmemSize**()<br>获取内核中ashmem区域的大小。  |
35| int | **GetProtection**()<br>获取内核中的ashmem区域的保护权限值。  |
36| bool | **MapAshmem**(int mapType)<br>将内核中的ashmem内存区域映射至用户空间。  |
37| bool | **MapReadAndWriteAshmem**()<br>以读/写模式映射ashmem内存区域。  |
38| bool | **MapReadOnlyAshmem**()<br>以只读模式映射ashmem内存区域。  |
39| const void * | **ReadFromAshmem**(int32_t size, int32_t offset)<br>从ashmem内存区域`offset`处读出数据。  |
40| bool | **SetProtection**(int protectionType)<br>设置内核中的ashmem区域的保护权限。  |
41| void | **UnmapAshmem**()<br>解除ashmem映射。  |
42| bool | **WriteToAshmem**(const void* data, int32_t size, int32_t offset)<br>在ashmem内存区域`offset`处写入数据。  |
43
44
45## 使用示例
46
471. 使用方法(伪代码)
48
49```c++
50sptr<Ashmem> ashmem = Ashmem::CreateAshmem(MEMORY_NAME.c_str(), MEMORY_SIZE);
51if (ashmem != nullptr) {
52    bool ret = ashmem->MapAshmem(PROT_READ | PROT_WRITE);
53}
54
55...
56
57// 当使用结束时不要忘记解映射和关闭ashmem
58ashmem->UnmapAshmem();
59ashmem->CloseAshmem();
60```
61
622. 测试用例编译运行方法
63
64- 测试用例代码参见 base/test/unittest/common/utils_ashmem_test.cpp
65
66- 使用开发者自测试框架，使用方法参见：[开发自测试执行框架-测试用例执行](https://gitee.com/openharmony/testfwk_developer_test#%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E6%89%A7%E8%A1%8C)
67
68- 使用以下具体命令以运行`ashmem.h`对应测试用例
69
70```bash
71run -t UT -tp utils -ts UtilsAshmemTest
72```
73
74## 常见问题
75
761. Ashmem对象使用结束后**需要手动解除映射并关闭**
77    * 智能指针仅管理Ashmem对象的析构，而Ashmem对象析构时不会解除内存空间的映射并关闭。
78    * 使用`UnmapAshmem()`解除映射并使用`CloseAshmem()`关闭。
79