diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml new file mode 100644 index 000000000..537396bb5 --- /dev/null +++ b/.github/workflows/docker.yml @@ -0,0 +1,35 @@ +name: Build Docker Image + +on: + push: + branches: [ develop, master ] + pull_request: + branches: [ develop, master ] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build Docker image + uses: docker/build-push-action@v5 + with: + context: . + file: ./Dockerfile + tags: seekdb:latest + load: true + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Test Docker image + run: | + # 这里可以添加一些基本的镜像测试命令 + # 例如检查镜像是否成功创建 + docker images | grep seekdb + echo "Docker image built successfully" \ No newline at end of file diff --git a/deps/oblib/src/rpc/obrpc/ob_rpc_proxy.ipp b/deps/oblib/src/rpc/obrpc/ob_rpc_proxy.ipp index a00831579..b27f9c46c 100644 --- a/deps/oblib/src/rpc/obrpc/ob_rpc_proxy.ipp +++ b/deps/oblib/src/rpc/obrpc/ob_rpc_proxy.ipp @@ -216,6 +216,7 @@ int ObRpcProxy::rpc_call(ObRpcPacketCode pcode, const Input &args, //do nothing } if (dst_ == ObRpcProxy::myaddr_) { + oceanbase::lib::Thread::WaitGuard guard(oceanbase::lib::Thread::WAIT); ret = oceanbase::oblpc::send(*this, pcode, args, result, handle, opts); } else { ret = OB_NOT_SUPPORTED; diff --git a/dockerfile b/dockerfile new file mode 100644 index 000000000..a83d84e69 --- /dev/null +++ b/dockerfile @@ -0,0 +1,26 @@ +# 使用与 GitHub Actions 相同的基础镜像 +FROM ubuntu:22.04 + +# 设置环境变量以避免交互式提示 +ENV DEBIAN_FRONTEND=noninteractive +ENV TZ=UTC + +# 设置工作目录 +WORKDIR /workspace + +# 安装构建所需的依赖包（与 GitHub Actions 中相同） +RUN apt-get update -y +RUN apt-get install -y git wget rpm rpm2cpio cpio make build-essential binutils m4 libtool-bin libncurses5 python3 +# RUN rm -rf /var/lib/apt/lists/* +# 复制项目文件到容器中 +COPY . . + +# 创建构建脚本 +RUN bash build.sh init + +# 将 deps 目录添加到 PATH +ENV PATH="/workspace/deps/3rd/usr/local/oceanbase/devtools/bin:${PATH}" +RUN bash build.sh debug -DOB_USE_CCACHE=ON +RUN ccache -z +RUN cd build_debug && make -j$(nproc) +RUN ccache -s diff --git a/docs/developer-guide/assets/favicon.ico b/docs/developer-guide/assets/favicon.ico index e69de29bb..9f938fad4 100644 Binary files a/docs/developer-guide/assets/favicon.ico and b/docs/developer-guide/assets/favicon.ico differ diff --git a/docs/developer-guide/assets/logo.png b/docs/developer-guide/assets/logo.png index e69de29bb..9c3714d78 100644 Binary files a/docs/developer-guide/assets/logo.png and b/docs/developer-guide/assets/logo.png differ diff --git a/docs/developer-guide/en/README.md b/docs/developer-guide/en/README.md index 730ab96f7..2ae0f4240 100644 --- a/docs/developer-guide/en/README.md +++ b/docs/developer-guide/en/README.md @@ -1,9 +1,9 @@ -# OceanBase SeekDB Development Guide +# OceanBase seekdb Development Guide ## About this guide -* **The target audience** of this guide is OceanBase SeekDB contributors, both new and experienced. -* **The objective** of this guide is to help contributors become an expert of OceanBase SeekDB, who is familiar with its design and implementation and thus is able to use it fluently in the real world as well as develop OceanBase SeekDB itself deeply. +* **The target audience** of this guide is OceanBase seekdb contributors, both new and experienced. +* **The objective** of this guide is to help contributors become an expert of OceanBase seekdb, who is familiar with its design and implementation and thus is able to use it fluently in the real world as well as develop OceanBase seekdb itself deeply. ## The structure of this guide @@ -11,7 +11,7 @@ At present, the guide is composed of the following parts: ### 1. Get Started -This section helps you set up the development environment and get OceanBase SeekDB running on your machine. Follow these steps in order if you're new to the project. +This section helps you set up the development environment and get OceanBase seekdb running on your machine. Follow these steps in order if you're new to the project. 1. [Install toolchain](toolchain.md) - Install the required development tools and dependencies 2. [Get the code, build and run](build-and-run.md) - Clone the repository, build the project, and connect to the seekdb server @@ -21,7 +21,7 @@ This section helps you set up the development environment and get OceanBase Seek Once you have the environment set up, these guides will help you develop effectively: 1. [Set up an IDE](ide-settings.md) - Configure your development environment for optimal productivity -2. [Coding Conventions](coding-convention.md) - Learn OceanBase SeekDB's programming habits and conventions +2. [Coding Conventions](coding-convention.md) - Learn OceanBase seekdb's programming habits and conventions 3. [Coding Standard](coding-standard.md) - Detailed C++ coding standards and constraints 4. [Write and run unit tests](unittest.md) - How to write and execute unit tests 5. [Running MySQL test](mysqltest.md) - How to run MySQL compatibility tests @@ -29,13 +29,13 @@ Once you have the environment set up, these guides will help you develop effecti ### 3. Understanding the Codebase -Before you start developing a big feature, it's recommended to read these documents to better understand OceanBase SeekDB's internals: +Before you start developing a big feature, it's recommended to read these documents to better understand OceanBase seekdb's internals: -1. [Logging System](logging.md) - How logging works in OceanBase SeekDB +1. [Logging System](logging.md) - How logging works in OceanBase seekdb 2. [Memory Management](memory.md) - Memory management strategies and best practices 3. [Basic Data Structures](container.md) - Core data structures used in the codebase -### 4. Contribute to OceanBase SeekDB +### 4. Contribute to OceanBase seekdb Ready to contribute? This guide will help you get involved in the OceanBase community: @@ -43,4 +43,4 @@ Ready to contribute? This guide will help you get involved in the OceanBase comm --- -**Note**: If you're new to the project, we recommend following the sections in order. Experienced contributors can jump directly to the sections they need. \ No newline at end of file +**Note**: If you're new to the project, we recommend following the sections in order. Experienced contributors can jump directly to the sections they need. diff --git a/docs/developer-guide/en/build-and-run.md b/docs/developer-guide/en/build-and-run.md index 15b1dd0ac..ab0a0bc1f 100644 --- a/docs/developer-guide/en/build-and-run.md +++ b/docs/developer-guide/en/build-and-run.md @@ -15,7 +15,7 @@ git clone https://github.com/oceanbase/seekdb.git ## Build -Build OceanBase SeekDB from the source code in debug mode or release mode: +Build OceanBase seekdb from the source code in debug mode or release mode: ### Debug mode @@ -31,7 +31,7 @@ bash build.sh release --init --make ## Run -Now that you built the `observer` binary, you can deploy a SeekDB instance with the `obd.sh` utility: +Now that you built the `observer` binary, you can deploy a seekdb instance with the `obd.sh` utility: ```shell ./tools/deploy/obd.sh prepare -p /tmp/obtest @@ -42,13 +42,13 @@ You can check the `mysql_port` in `./tools/deploy/single.yaml` file to see the l ## Connect -You can use the official MySQL client to connect to SeekDB: +You can use the official MySQL client to connect to seekdb: ```shell mysql -uroot -h127.0.0.1 -P10000 ``` -Alternatively, you can use the `obclient` to connect to SeekDB: +Alternatively, you can use the `obclient` to connect to seekdb: ```shell ./deps/3rd/u01/obclient/bin/obclient -h127.0.0.1 -P10000 -uroot -Doceanbase -A diff --git a/docs/developer-guide/en/coding-convention.md b/docs/developer-guide/en/coding-convention.md index 793e9aa76..206cf7669 100644 --- a/docs/developer-guide/en/coding-convention.md +++ b/docs/developer-guide/en/coding-convention.md @@ -2,7 +2,7 @@ title: Coding Convention --- -OceanBase SeekDB is a giant project that has been developed for more than ten years and contains millions of lines of C++ code. It already has many unique programming habits. Here are some OceanBase SeekDB programming habits to help people who come into contact with the OceanBase SeekDB source code for the first time have an easier time accepting and understanding. For more detailed information, please refer to ["OceanBase SeekDB C++ Coding Standard"](./coding_standard.md). +OceanBase seekdb is a giant project that has been developed for more than ten years and contains millions of lines of C++ code. It already has many unique programming habits. Here are some OceanBase seekdb programming habits to help people who come into contact with the OceanBase seekdb source code for the first time have an easier time accepting and understanding. For more detailed information, please refer to ["OceanBase seekdb C++ Coding Standard"](./coding-standard.md). # Naming Convention @@ -20,7 +20,7 @@ Both function names and variables use lowercase naming separated by `_`. Member # Coding Style -SeekDB uses some relatively simple coding styles to try to make the code readable and clear, such as adding necessary spaces for operator brackets, not too long codes, not too long functions, adding necessary comments, reasonable naming, etc. Since the coding style has many details, new developers can just refer to the coding style in the current code to write code. This is also a suggestion for participating in other projects for the first time. We should try to keep it consistent with the original style. +seekdb uses some relatively simple coding styles to try to make the code readable and clear, such as adding necessary spaces for operator brackets, not too long codes, not too long functions, adding necessary comments, reasonable naming, etc. Since the coding style has many details, new developers can just refer to the coding style in the current code to write code. This is also a suggestion for participating in other projects for the first time. We should try to keep it consistent with the original style. There is no need to worry about the styles that you are not sure about. You can discuss it with us, or after submitting the code, someone will give suggestions or code together. @@ -28,21 +28,21 @@ There is no need to worry about the styles that you are not sure about. You can ## Prohibitting STL Containers -Since SeekDB supports multi-tenants resource isolation, in order to facilitate memory control, SeekDB prohibits the use of STL, boost and other containers. At the same time, SeekDB provides its own containers, such as `ObSEArray`, etc. For more information about SeekDB containers, please refer to [OceanBase SeekDB Container Introduction] (./container.md). +Since seekdb supports multi-tenants resource isolation, in order to facilitate memory control, seekdb prohibits the use of STL, boost and other containers. At the same time, seekdb provides its own containers, such as `ObSEArray`, etc. For more information about seekdb containers, please refer to [OceanBase seekdb Container Introduction] (./container.md). ## Be Caution with the New C++ Standard -SeekDB does not encourage the use of some syntax of the new C++ standard, such as auto, smart pointers, move semantics, range-based loops, lambda, etc. SeekDB believes that these will bring many negative effects, such as +seekdb does not encourage the use of some syntax of the new C++ standard, such as auto, smart pointers, move semantics, range-based loops, lambda, etc. seekdb believes that these will bring many negative effects, such as - Improper use of `auto` can cause serious performance problems, but it only brings syntactic convenience; - Smart pointers cannot solve the problem of object memory usage, and improper use can also cause performance problems; - The use of move is extremely complex, and it will lead to deeply hidden BUGs without ensuring that everyone understands it correctly. -Of course, SeekDB does not exclude all new standards, such as encouraging the use of override, final, constexpr, etc. If you are not sure whether a certain syntax can be used, you can search and confirm in ["OceanBase SeekDB C++ Coding Standard"](./coding_standard.md). +Of course, seekdb does not exclude all new standards, such as encouraging the use of override, final, constexpr, etc. If you are not sure whether a certain syntax can be used, you can search and confirm in ["OceanBase seekdb C++ Coding Standard"](./coding-standard.md). ## Single Entrance and Single Exit -It is mandatory for all functions to return at the end, and it is prohibited to call global jump instructions such as return, goto, and exit midway. This is also the most confusing part for everyone who comes into contact with SeekDB code for the first time. +It is mandatory for all functions to return at the end, and it is prohibited to call global jump instructions such as return, goto, and exit midway. This is also the most confusing part for everyone who comes into contact with seekdb code for the first time. In order to achieve this requirement, there will be a lot of `if/else if` in the code, and there are many less intuitive conditional judgments such as `OB_SUCC(ret)` in the `for` loop. At the same time, in order to reduce nesting, the macro `FALSE_IT` will be used to execute certain statements. for example @@ -102,7 +102,7 @@ Or similar simple judgment functions do not need to return int error codes. ## Need to Determine the Validity of All Return Values and Parameters -SeekDB requires that as long as the function has a return value, the return value must be tested, and "check if possible." Function parameters, especially pointers, must be checked for validity before use. +seekdb requires that as long as the function has a return value, the return value must be tested, and "check if possible." Function parameters, especially pointers, must be checked for validity before use. For example: @@ -127,9 +127,9 @@ int ObDDLServerClient::abort_redef_table(const obrpc::ObAbortRedefTableArg &arg, ## Memory Management -Memory management is a very troublesome issue in C/C++ programs. SeekDB has done a lot of work for memory management, including efficient memory allocation, memory problem detection, tenant memory isolation, etc. SeekDB provides a set of memory management mechanisms for this purpose, and also prohibits the direct use of C/C++ native memory allocation interfaces in programs, such as malloc, new, etc. +Memory management is a very troublesome issue in C/C++ programs. seekdb has done a lot of work for memory management, including efficient memory allocation, memory problem detection, tenant memory isolation, etc. seekdb provides a set of memory management mechanisms for this purpose, and also prohibits the direct use of C/C++ native memory allocation interfaces in programs, such as malloc, new, etc. -The simplest, SeekDB provides the `ob_malloc/ob_free` interface to allocate and release memory: +The simplest, seekdb provides the `ob_malloc/ob_free` interface to allocate and release memory: ```cpp void *ptr = ob_malloc(100, ObModIds::OB_COMMON_ARRAY); @@ -143,18 +143,18 @@ if (NULL != ptr) { } ``` -SeekDB requires that the pointer must be assigned to null immediately after the memory is released. -For more information about memory management, please refer to [OceanBase SeekDB Memory Management](./memory.md). +seekdb requires that the pointer must be assigned to null immediately after the memory is released. +For more information about memory management, please refer to [OceanBase seekdb Memory Management](./memory.md). # Some Conventional Interfaces ## init/destroy -SeekDB requires that only some very lightweight data initialization work can be implemented in the constructor, such as variables initialized to 0, pointers initialized to nullptr, etc. Because in the constructor, it is not easy to handle some complex exception scenarios, and the return value cannot be given. Most classes in SeekDB have an init function, which is usually executed after the constructor and has an int error code as the return value. Do some more complex initialization work here. Correspondingly, the destroy function is usually provided to do resource destruction. +seekdb requires that only some very lightweight data initialization work can be implemented in the constructor, such as variables initialized to 0, pointers initialized to nullptr, etc. Because in the constructor, it is not easy to handle some complex exception scenarios, and the return value cannot be given. Most classes in seekdb have an init function, which is usually executed after the constructor and has an int error code as the return value. Do some more complex initialization work here. Correspondingly, the destroy function is usually provided to do resource destruction. ## reuse/reset -Memory caching is a very effective way of improving performance. Many classes in SeekDB will have reuse/reset interfaces to facilitate the subsequent reuse of an object. Reuse usually represents lightweight cleanup work, while reset will do more resource cleanup work. But you need to look at the specific implementation class and cannot generalize. +Memory caching is a very effective way of improving performance. Many classes in seekdb will have reuse/reset interfaces to facilitate the subsequent reuse of an object. Reuse usually represents lightweight cleanup work, while reset will do more resource cleanup work. But you need to look at the specific implementation class and cannot generalize. ## Operator Overloading diff --git a/docs/developer-guide/en/coding-standard.md b/docs/developer-guide/en/coding-standard.md index 45aa33cf5..0f1a85b8a 100644 --- a/docs/developer-guide/en/coding-standard.md +++ b/docs/developer-guide/en/coding-standard.md @@ -7,7 +7,7 @@ title: Coding Standard | 1 | 1.0 | | New | Nov 7th, 2025 | # 1 Introduction -This coding standard is applicable to the OceanBase SeekDB project of Ant Group. It provides some coding constraints and defines coding styles. In the OceanBase SeekDB project, the kernel code must comply with the coding style of this document, the test code is recommended to comply with the coding constraints of this document, and other codes must also comply with the coding constraints and coding style of this document. +This coding standard is applicable to the OceanBase seekdb project of Ant Group. It provides some coding constraints and defines coding styles. In the OceanBase seekdb project, the kernel code must comply with the coding style of this document, the test code is recommended to comply with the coding constraints of this document, and other codes must also comply with the coding constraints and coding style of this document. This coding standard is committed to writing C/C++ code that is easy to understand, reduces traps, and has a unified format. Therefore: @@ -336,7 +336,7 @@ b.cpp &bbb=0x400798 Simple variable declarations should be initialized when declared. -OceanBase SeekDB believes that declaring variables at the beginning of each statement block leads to more readable code. Additionally, OceanBase SeekDB allows for code such as `for (int i = 0; i < 10; ++i)` where the variable 'i' is declared at the beginning of the loop statement block. If the declaration and use of a variable are far apart, it indicates that the statement block contains too much code, which often means that the code needs to be refactored. +OceanBase seekdb believes that declaring variables at the beginning of each statement block leads to more readable code. Additionally, OceanBase seekdb allows for code such as `for (int i = 0; i < 10; ++i)` where the variable 'i' is declared at the beginning of the loop statement block. If the declaration and use of a variable are far apart, it indicates that the statement block contains too much code, which often means that the code needs to be refactored. Declaring variables inside a loop body can be inefficient, as the constructor and destructor of an object will be called each time the loop iterates, and the variable will need to be pushed and popped from the stack each time. Therefore, it is recommended to extract such variables from the loop body to improve efficiency. **It is prohibited to declare complex variables** (e.g. class variables) inside a loop body, but if it is necessary to do so, approval from the team leader must be obtained, and a detailed comment explaining the reason must be provided. For the sake of code readability, declaring references inside a loop body is allowed. @@ -362,7 +362,7 @@ for(int i = 0; i < N; ++i) { } ``` -In addition, OceanBase SeekDB sets limits on the size of local variables and does not recommend defining excessively large local variables. +In addition, OceanBase seekdb sets limits on the size of local variables and does not recommend defining excessively large local variables. 1. The function stack should not exceed 32K. 2. A single local variable should not exceed 8K. @@ -426,7 +426,7 @@ Before C\+\+11, the C\+\+98 standard only allowed static const variables of inte **Case 1** -According to the current code style of OceanBase SeekDB, we will define static variables (such as `ob_define.h`) in the header file, so that each cpp file will generate a declaration and definition of this variable when including this header file. In particular, some large objects (latch, wait event, etc.) generate a static definition in the header file, resulting in the generation of binary and memory expansion. +According to the current code style of OceanBase seekdb, we will define static variables (such as `ob_define.h`) in the header file, so that each cpp file will generate a declaration and definition of this variable when including this header file. In particular, some large objects (latch, wait event, etc.) generate a static definition in the header file, resulting in the generation of binary and memory expansion. Simply move the definition of several static variables from the header file to the cpp file, and change the header file to extern definition, the effect is quite obvious: binary size: 2.6G->2.4G, reduce 200M. @@ -843,7 +843,7 @@ All inheritance must be `public`, and inheritance must be used with care: use in When a subclass inherits from a parent class, the subclass contains all the data and operation definitions of the parent class. In C++ practice, inheritance is mainly used in two scenarios: implementation inheritance, where the subclass inherits the implementation code of the parent class; interface inheritance, where the subclass inherits the method name of the parent class. For implementation inheritance, because the code that implements the subclass is extended between the parent class and the subclass, it becomes more difficult to understand its implementation, and it should be used with caution. -Multiple inheritance is also used in OceanBase SeekDB. The scenario is rare, and requires at most one base class to contain implementation, and other base classes are pure interface classes. +Multiple inheritance is also used in OceanBase seekdb. The scenario is rare, and requires at most one base class to contain implementation, and other base classes are pure interface classes. ## 4.10 Operator Overloading **Except for container classes, custom data types (`ObString`, `ObNumber`, etc.) and a few global basic classes such as `ObRowkey`, `ObObj`, `ObRange`, etc., do not overload operators (except simple structure assignment operations)**. If it must be violated, please discuss and approve it in advance, and explain the reasons in detail. @@ -1003,7 +1003,7 @@ if (OB_SUCCESS == ret) { // start a new logic } ``` -In the actual coding process, when should concise writing be used? OceanBase SeekDB believes that when each step of a sequential statement has only one line of statement, and these steps are logically coupled tightly, the concise writing method should be used as much as possible. However, if it logically belongs to multiple sections, each of which does a different thing, then brevity should only be used within each section, not brevity for the sake of brevity. +In the actual coding process, when should concise writing be used? OceanBase seekdb believes that when each step of a sequential statement has only one line of statement, and these steps are logically coupled tightly, the concise writing method should be used as much as possible. However, if it logically belongs to multiple sections, each of which does a different thing, then brevity should only be used within each section, not brevity for the sake of brevity. It should be noted that if the sequential statement is followed by a conditional statement. If sequential statements are reduced to conditional statements, then they cannot be combined into one large conditional statement, but should be separated in code structure. For example: ```cpp @@ -1140,7 +1140,7 @@ if (cond1 && cond2) { } ``` -The first writing method is divided into two layers, and the second writing method is divided into one layer. OceanBase SeekDB only allows the first writing method. Of course, `cond1` and `cond2` here are from the perspective of business logic, referring to two independent business logics, rather than saying that `cond1` and `cond2` cannot contain `&&` or `||` operators. For example: +The first writing method is divided into two layers, and the second writing method is divided into one layer. OceanBase seekdb only allows the first writing method. Of course, `cond1` and `cond2` here are from the perspective of business logic, referring to two independent business logics, rather than saying that `cond1` and `cond2` cannot contain `&&` or `||` operators. For example: ```cpp // Whether app_name is empty, including || @@ -1222,7 +1222,7 @@ int ret = do_something(param1, NUM_TIMES, null_callback); ## 5.9 Pointer or Reference Function parameters can choose pointers or references. Use more references while respecting idioms. -Pointer parameters and reference parameters can often achieve the same effect. Considering that the OceanBase SeekDB coding specification has strict requirements for error judgment, more references are used to reduce some redundant error judgment codes. Provided, of course, that idioms are followed, such as: +Pointer parameters and reference parameters can often achieve the same effect. Considering that the OceanBase seekdb coding specification has strict requirements for error judgment, more references are used to reduce some redundant error judgment codes. Provided, of course, that idioms are followed, such as: 1. The method of applying for an object often returns a pointer, and the corresponding release method also passes in a pointer. 2. If the member of the object is a pointer, the corresponding `set_xxx` input is also a pointer. @@ -1230,7 +1230,7 @@ Pointer parameters and reference parameters can often achieve the same effect. C ## 5.10 Function Length It is mandatory that a single function does not exceed 120 lines. If it must be violated, please obtain the consent of the group leader in advance, and explain the reasons in detail. -Most open source projects limit the number of lines of a single function. Generally speaking, functions with more than 80 lines are often inappropriate. Considering that OceanBase SeekDB has a lot of redundant error judgment codes, a single function is limited to no more than 120 lines. If the function is too long, consider splitting it into several smaller and more manageable functions, or re-examine the design and modify the structure of the class. +Most open source projects limit the number of lines of a single function. Generally speaking, functions with more than 80 lines are often inappropriate. Considering that OceanBase seekdb has a lot of redundant error judgment codes, a single function is limited to no more than 120 lines. If the function is too long, consider splitting it into several smaller and more manageable functions, or re-examine the design and modify the structure of the class. ## 5.11 Summary 1. **Strictly abide by the single-entry single-exit function. If it must be violated, please obtain the consent of the project leader and project architect in advance, and explain the reasons in detail.** @@ -1246,20 +1246,20 @@ Most open source projects limit the number of lines of a single function. Genera 11. It is mandatory that a single function does not exceed 120 lines. If it must be violated, please obtain the consent of the group leader in advance, and explain the reasons in detail. # 6 C&C++ Features -The advantage of C++ is flexibility, and the disadvantage is also flexibility. For many functions of C++, OceanBase SeekDB is conservative, and this section describes some of them. There are two principles for choosing these features: +The advantage of C++ is flexibility, and the disadvantage is also flexibility. For many functions of C++, OceanBase seekdb is conservative, and this section describes some of them. There are two principles for choosing these features: 1. Principle of caution: This feature is relatively "safe", even for beginners, there are not too many "pitfalls" -2. Necessity: It has "sufficient" benefits to improve the coding quality of OceanBase SeekDB +2. Necessity: It has "sufficient" benefits to improve the coding quality of OceanBase seekdb ## 6.1 Smart Pointers and Resource Guard Smart pointers are not allowed, allowing automatic release of resources through the Guard class. -The boost library supports smart pointers, including `scoped_ptr`, `shared_ptr`, and `auto_ptr`. Many people think that smart pointers can be used safely, especially `scoped_ptr`. However, most of OceanBase SeekDB's existing code releases resources manually, and smart pointers are prone to side effects if they are not used well. Therefore, smart pointers are not allowed. +The boost library supports smart pointers, including `scoped_ptr`, `shared_ptr`, and `auto_ptr`. Many people think that smart pointers can be used safely, especially `scoped_ptr`. However, most of OceanBase seekdb's existing code releases resources manually, and smart pointers are prone to side effects if they are not used well. Therefore, smart pointers are not allowed. Users are allowed to write some Guard classes by hand. The methods of these classes will apply for some resources, and these resources will be released automatically when the class is destroyed, such as LockGuard and SessionGuard. ## 6.2 Memory Allocation and Release It is required to use the memory allocator to allocate memory, and immediately set the pointer to NULL after the memory is released. -The methods OceanBase SeekDB can use for memory allocation include `ob_malloc` and various memory allocators. It is required to use the memory allocator to allocate memory, and specify the module it belongs to when allocating. The advantage of this is that it is convenient for the system to manage memory. If there is a memory leak, it is easy to see which module it is. In addition, it is necessary to prevent reference to the memory space that has been released, and it is required to set the pointer to `NULL` immediately after free. +The methods OceanBase seekdb can use for memory allocation include `ob_malloc` and various memory allocators. It is required to use the memory allocator to allocate memory, and specify the module it belongs to when allocating. The advantage of this is that it is convenient for the system to manage memory. If there is a memory leak, it is easy to see which module it is. In addition, it is necessary to prevent reference to the memory space that has been released, and it is required to set the pointer to `NULL` immediately after free. ```cpp void *ptr = ob_malloc(100, ObModIds::OB_COMMON_ARRAY); @@ -1276,7 +1276,7 @@ if (NULL != ptr) { ## 6.3 String The `std::string` class is prohibited, and `ObString` is used instead. In addition, when manipulating C strings, it is required to use length-limited string functions. -C++'s `std::string` class is very convenient to use. The problem is that it is impossible to figure out its internal behavior, such as copying and implicit conversion. OceanBase SeekDB requires the use of `ObString` as much as possible, and the memory used in it needs to be manually managed by developers. +C++'s `std::string` class is very convenient to use. The problem is that it is impossible to figure out its internal behavior, such as copying and implicit conversion. OceanBase seekdb requires the use of `ObString` as much as possible, and the memory used in it needs to be manually managed by developers. Sometimes C strings are used. Be careful not to use string manipulation functions with unlimited length, including `strcpy/strcat/strdup/sprintf/strncpy`, but use the corresponding string manipulation functions with limited length `strncat/strndup/snprintf/memcpy`. You can use strlen to get the length of a string. The reason why `strncpy` is not used is that if the incoming buffer is not enough, it will not automatically '\0', and there are performance problems, so it needs to be replaced by `memcpy/snprintf`. @@ -1372,7 +1372,7 @@ The principle of judgment is: in addition to output and serialization, as long a ## 6.14 Boost and STL **In STL, only algorithm functions defined in the header file are allowed, such as std_sort, and other STL or boost functions are prohibited. If it must be violated, please obtain the consent of the project leader and project architect in advance, and explain the reasons in detail.** -OceanBase SeekDB has a conservative attitude towards libraries like boost and STL, and we believe that writing code correctly is far more important than writing code conveniently. Except for the algorithm class functions defined by STL , other functions should not be used. +OceanBase seekdb has a conservative attitude towards libraries like boost and STL, and we believe that writing code correctly is far more important than writing code conveniently. Except for the algorithm class functions defined by STL , other functions should not be used. ## 6.15 auto **What is** @@ -1401,7 +1401,7 @@ for(const auto& kvp : map) { ``` **Is it allowed** **Prohibited.** -This feature is just a syntactic sugar. The `FOREACH` macro defined by ourselves has been widely used in the previous OceanBase SeekDB code, which can achieve similar effects. +This feature is just a syntactic sugar. The `FOREACH` macro defined by ourselves has been widely used in the previous OceanBase seekdb code, which can achieve similar effects. ## 6.17 Override and Final **What is** @@ -1430,7 +1430,7 @@ public: **Is it allowed** **Allow.** `override` and `final` are not only allowed, but strongly recommended, and should be added wherever they can be used. -According to previous experience, the overloading of the virtual function in the OceanBase SeekDB missed the `const`, resulting in endless errors of overloading errors. It is required that in the new code, all overloads must be added with override to avoid this wrong overload situation. +According to previous experience, the overloading of the virtual function in the OceanBase seekdb missed the `const`, resulting in endless errors of overloading errors. It is required that in the new code, all overloads must be added with override to avoid this wrong overload situation. In addition to being used for virtual functions, when a class is added with the final keyword, it means that it cannot be further derived, which is conducive to compiler optimization. When such a class has no parent class, the destructor does not need to add virtual. @@ -1479,7 +1479,7 @@ std::for_each(std::begin(arr), std::end(arr), [](int n) {std::cout << n << std:: ``` **Is it allowed** -**Prohibited**. This feature is mainly to make STL easier to use, but OceanBase SeekDB prohibits the use of STL containers. +**Prohibited**. This feature is mainly to make STL easier to use, but OceanBase seekdb prohibits the use of STL containers. ## 6.21 static_assert and Type Traits **What is** @@ -1512,9 +1512,9 @@ Buffer(Buffer&& temp): ``` **Is it allowed** **Prohibited**. Banning it may bring some controversy. Mainly based on the following considerations: -1. OceanBase SeekDB does not use STL containers, so the optimization of the standard library using move semantics does not bring us benefits. +1. OceanBase seekdb does not use STL containers, so the optimization of the standard library using move semantics does not bring us benefits. 2. The semantics of move semantic and rvalue are more complicated, and it is easy to introduce pitfalls -3. Using it to transform some existing containers of OceanBase SeekDB can indeed improve performance. However, the memory management method of OceanBase SeekDB has made the use of move semantics smaller. In many cases, we have optimized it during implementation, and only store pointers in the container, not large objects. +3. Using it to transform some existing containers of OceanBase seekdb can indeed improve performance. However, the memory management method of OceanBase seekdb has made the use of move semantics smaller. In many cases, we have optimized it during implementation, and only store pointers in the container, not large objects. It is recommended to consider other C++11 features after a period of familiarity, when the coding standard is revised next time. @@ -1545,7 +1545,7 @@ X* p = new X{1,2}; ``` **Is it allowed** -**Prohibited**. Syntactically more uniform, but again without any significant benefit. At the same time, it will significantly affect the style of OceanBase SeekDB code and affect readability. +**Prohibited**. Syntactically more uniform, but again without any significant benefit. At the same time, it will significantly affect the style of OceanBase seekdb code and affect readability. ## 6.24 Right Angle Brackets **What is** Fix a common syntax problem in original C. It turns out that when the templates of C-defined templates are nested, the ending >> must be separated by spaces, which is no longer needed. @@ -1571,7 +1571,7 @@ void func(const Arg1& arg1, const Args&... args) } ``` **Is it allowed** -**Allow**. This is a key feature for template programming. Because there is no variable-length template parameter, some basic libraries of OceanBase SeekDB, such as `to_string`, `to_yson`, RPC framework, log library, etc., need to be implemented with some tricks and macros. And more type safe. +**Allow**. This is a key feature for template programming. Because there is no variable-length template parameter, some basic libraries of OceanBase seekdb, such as `to_string`, `to_yson`, RPC framework, log library, etc., need to be implemented with some tricks and macros. And more type safe. ## 6.26 Unrestricted Unions **What is** @@ -1593,7 +1593,7 @@ union_{ }; ``` **Is it allowed** -**Allow**. There are many places in the OceanBase SeekDB code that have to define redundant domains because of this limitation, or use tricky methods to bypass (define char array placeholders). See `sql::ObPostExprItem` for a miserable example. +**Allow**. There are many places in the OceanBase seekdb code that have to define redundant domains because of this limitation, or use tricky methods to bypass (define char array placeholders). See `sql::ObPostExprItem` for a miserable example. ## 6.27 Explicitly Defaulted and Deleted Special Member Functions **What is** @@ -1612,7 +1612,7 @@ struct NoInt { ``` **Is it allowed** -**Allowed**. This feature is like tailor-made for OceanBase SeekDB; the function of disabling a certain function is also very useful. +**Allowed**. This feature is like tailor-made for OceanBase seekdb; the function of disabling a certain function is also very useful. ## 6.28 Type Alias (Alias Declaration) **What is** Use the new alias declaration syntax to define an alias of a type, similar to the previous typedef; moreover, you can also define an alias template. @@ -2281,7 +2281,7 @@ For functions that have not been implemented or are not perfectly implemented, s 2. In order to ensure that a thread will not be busy waiting in an infinite loop when exiting, the loop generally needs to judge the stop flag. ## 10.2 pthread_key 1. There are only 1024 `pthread_key` at most, and this limit cannot be increased, so special attention should be paid when using it. -2. If you want to use a large number of thread-local variables, it is recommended to use the thread number as an array subscript to obtain a thread-private variable. An `itid()` function is encapsulated in the OceanBase SeekDB to obtain continuously increasing thread numbers. +2. If you want to use a large number of thread-local variables, it is recommended to use the thread number as an array subscript to obtain a thread-private variable. An `itid()` function is encapsulated in the OceanBase seekdb to obtain continuously increasing thread numbers. ```cpp void *get_thread_local_variable() diff --git a/docs/developer-guide/en/container.md b/docs/developer-guide/en/container.md index 3ecdb791f..0620966db 100644 --- a/docs/developer-guide/en/container.md +++ b/docs/developer-guide/en/container.md @@ -4,16 +4,16 @@ title: Basic Data Structures # Introduction -C++ STL provides many convenient containers, such as vector, map, unordered_map, etc. Due to SeekDB programming style and memory control, the use of STL containers is prohibited in SeekDB. SeekDB provides some container implementations, including arrays, linked lists, HashMap, etc. This document will introduce some of these containers. +C++ STL provides many convenient containers, such as vector, map, unordered_map, etc. Due to seekdb programming style and memory control, the use of STL containers is prohibited in seekdb. seekdb provides some container implementations, including arrays, linked lists, HashMap, etc. This document will introduce some of these containers. > This document assumes that you already have a certain understanding of C++ STL containers. -> pair does not belong to the container, so it can be used in SeekDB. +> pair does not belong to the container, so it can be used in seekdb. -> Due to historical reasons, SeekDB contains some container code that is no longer recommended but has not been deleted. +> Due to historical reasons, seekdb contains some container code that is no longer recommended but has not been deleted. # String -The string class provided by SeekDB is ObString. Code reference ob_string.h. +The string class provided by seekdb is ObString. Code reference ob_string.h. Before introducing ObString's interface, let's first look at ObSring's memory management method, which will make it easier to understand ObString's interface design. @@ -94,7 +94,7 @@ ObString also has some other interfaces, just browse the ob_string.h code if nee # Array -SeekDB's array interface design is similar to STL vector, but it is more in line with SeekDB's style. For example, the interface will have an int return value indicating success or failure of execution. SeekDB provides multiple arrays with different implementations, but the interfaces they provide are similar. +seekdb's array interface design is similar to STL vector, but it is more in line with seekdb's style. For example, the interface will have an int return value indicating success or failure of execution. seekdb provides multiple arrays with different implementations, but the interfaces they provide are similar. Commonly used array implementation classes all inherit the same interface `ObIArray`. Let's take a look at the interface definition first, and then introduce the differences between different array implementations. @@ -180,7 +180,7 @@ int assign(const ObIArray &other); ``` ## ObArray -ObArray manages memory by itself. When declaring the ObArray template class, you need to specify an allocator, or use the default allocator `ModulePageAllocator`. Since SeekDB requires all actions to determine the return value, it is not recommended to use ObArray's `operator=` and other functions without return values. +ObArray manages memory by itself. When declaring the ObArray template class, you need to specify an allocator, or use the default allocator `ModulePageAllocator`. Since seekdb requires all actions to determine the return value, it is not recommended to use ObArray's `operator=` and other functions without return values. Many behaviors of ObArray are similar to STL vectors. Each time the memory is expanded, the behavior is similar. It will expand twice the current data size, but up to `block_size_` size. A `block_size_` default value is `OB_MALLOC_NORMAL_BLOCK_SIZE` (think of it as 8K). @@ -364,7 +364,7 @@ bool is_empty() const int32_t get_size() const ``` -SeekDB provides auxiliary `DLinkNode` implementations `ObDLinkNode` and `ObDLinkDerived`, making it easy to use ObDList simply by using either replication class. +seekdb provides auxiliary `DLinkNode` implementations `ObDLinkNode` and `ObDLinkDerived`, making it easy to use ObDList simply by using either replication class. Before introducing these two auxiliary classes, let's take a brief look at a basic auxiliary interface implementation `ObDLinkBase`, which is the base class of the above two auxiliary classes. It contains the front and rear node pointers required by ObDList and some basic node operations. Both auxiliary classes are implemented by inheriting the base class, and only use different methods. @@ -416,9 +416,9 @@ Since ObDList does not manage the memory of nodes, you need to be careful when u # Map Map is a commonly used data structure, and its insertion and query efficiency are very high. Normally, there are two implementation methods for Map. One is a balanced search tree, typically a red-black tree. Common compilers use this method to implement it. The other is a hash table, which is unordered_map in STL. -There are many Maps implemented in SeekDB, including the balanced search tree implementation ObRbTree and hash maps suitable for different scenarios, such as ObHashMap, ObLinkHashMap and ObLinearHashMap. +There are many Maps implemented in seekdb, including the balanced search tree implementation ObRbTree and hash maps suitable for different scenarios, such as ObHashMap, ObLinkHashMap and ObLinearHashMap. -> SeekDB implements many types of hash maps, but it is recommended to use the few introduced here unless you have a clear understanding of other implementations. +> seekdb implements many types of hash maps, but it is recommended to use the few introduced here unless you have a clear understanding of other implementations. ## ObHashMap The implementation of ObHashMap is in ob_hashmap.h. In order to facilitate the understanding of the implementation of ObHashMap, I will introduce it with reference to STL::unordered_map. @@ -437,7 +437,7 @@ template< Key in the template parameters is our key, T is the type of our value, Hash is a class or function that calculates the hash value based on the key, KeyEqual is a method to determine whether two key values are equal, and Allocator is an allocator. An object is a pair of keys and values. -The declaration in SeekDB is similar: +The declaration in seekdb is similar: ```cpp template int remove_if(Function &fn); ``` ## ObRbTree -ObRbTree is a red-black tree implementation that supports basic operations such as insertion, deletion, and search, and is not thread-safe. Since ObRbTree is not used in SeekDB, it will not be introduced again. If you are interested, please read the source code `ob_rbtree.h`. +ObRbTree is a red-black tree implementation that supports basic operations such as insertion, deletion, and search, and is not thread-safe. Since ObRbTree is not used in seekdb, it will not be introduced again. If you are interested, please read the source code `ob_rbtree.h`. # Others -SeekDB also has many basic container implementations, such as some queues (ObFixedQueue, ObLightyQueue, ObLinkQueue), bitmap (ObBitmap), tuple (ObTuple), etc. If the common containers don't meet your needs, you can find more in the `deps/oblib/src/lib` directory. +seekdb also has many basic container implementations, such as some queues (ObFixedQueue, ObLightyQueue, ObLinkQueue), bitmap (ObBitmap), tuple (ObTuple), etc. If the common containers don't meet your needs, you can find more in the `deps/oblib/src/lib` directory. diff --git a/docs/developer-guide/en/contributing.md b/docs/developer-guide/en/contributing.md index 74c223269..2be92ea0a 100644 --- a/docs/developer-guide/en/contributing.md +++ b/docs/developer-guide/en/contributing.md @@ -82,4 +82,4 @@ git push -u origin $new_branch_name ![CLA](https://user-images.githubusercontent.com/5435903/204097095-6a19d2d1-ee0c-4fb6-be2d-77f7577d75d2.png#crop=0&crop=0&crop=1&crop=1&from=url&id=Mmj8a&margin=%5Bobject%20Object%5D&originHeight=271&originWidth=919&originalType=binary&ratio=1&rotation=0&showTitle=false&status=done&style=none&title=) -After you submit your updates, OceanBase SeekDB will review and comment if needed. Once we approve your updates, the system will automatically run CI testing and stress testing. If no issues are found in the tests, your updates will be merged. Now you have successfully completed your contribution task and become one of our contributors. +After you submit your updates, OceanBase seekdb will review and comment if needed. Once we approve your updates, the system will automatically run CI testing and stress testing. If no issues are found in the tests, your updates will be merged. Now you have successfully completed your contribution task and become one of our contributors. diff --git a/docs/developer-guide/en/debug.md b/docs/developer-guide/en/debug.md index 4c1e1df10..b5b0d2a37 100644 --- a/docs/developer-guide/en/debug.md +++ b/docs/developer-guide/en/debug.md @@ -4,12 +4,12 @@ title: Debug # Abstract -This document describes some methods to debug OceanBase SeekDB. We have many ways to debug SeekDB, such as gdb, logging, etc. +This document describes some methods to debug OceanBase seekdb. We have many ways to debug seekdb, such as gdb, logging, etc. -We suggest you build SeekDB with debug mode as it is easy to debug. +We suggest you build seekdb with debug mode as it is easy to debug. # GDB -GDB is a powerful debugging tool, but it is difficult to debug SeekDB by gdb and the scenarios are limited. +GDB is a powerful debugging tool, but it is difficult to debug seekdb by gdb and the scenarios are limited. If you want to debug a single oceanbase process and single thread, you can use gdb, otherwise it is more recommended to use logging. @@ -37,7 +37,7 @@ Then you can set breakpoint, print variable, etc. Please refer to [gdb manual](h ## Debug oceanbase with debug-info package If you want to debug oceanbase or check the coredump file deployed with oceanbase rpm, you should install or load the debug-info package first. Loading is more recommended although installation is more convenient as there will be many debug-info packages in the system and it is not easy to cleanup. -First, obtain the debug-info package from the website, and then load the package into gdb. Afterward, you will be able to debug SeekDB with ease. +First, obtain the debug-info package from the website, and then load the package into gdb. Afterward, you will be able to debug seekdb with ease. Below are some tips. @@ -48,7 +48,7 @@ You can get the package revision by the command below. # in the observer runtime path clusters/local/bin [83] $ ./observer -V ./observer -V -observer (OceanBase SeekDB 1.0.0.0) +observer (OceanBase seekdb 1.0.0.0) REVISION: 102000042023061314-43bca414d5065272a730c92a645c3e25768c1d05 BUILD_BRANCH: HEAD @@ -69,7 +69,7 @@ You can run command below to get the revision ```bash clusters/local/bin [83] $ LD_LIBRARY_PATH=../lib:$LD_LIBRARY_PATH ./observer -V ./observer -V -observer (OceanBase SeekDB 1.0.0.0) +observer (OceanBase seekdb 1.0.0.0) REVISION: 102000042023061314-43bca414d5065272a730c92a645c3e25768c1d05 BUILD_BRANCH: HEAD @@ -190,7 +190,7 @@ Let's run the debug command again and we can get detailed information. ``` # Logging -Logging is the most common way to debug SeekDB, and it is easy to use and can be used in most scenarios. +Logging is the most common way to debug seekdb, and it is easy to use and can be used in most scenarios. In common scenarios, we can add logs in the code and print the variable, then rebuild and redeploy the oceanbase. ## How to add logs @@ -317,9 +317,9 @@ obclient> show trace; # Debug Sync -If you use gdb to debug SeekDB, it maybe cannot work normally because gdb will hang the process and SeekDB depends on the heartbeat to work normally. So we provide a debug sync mechanism to solve this problem. +If you use gdb to debug seekdb, it maybe cannot work normally because gdb will hang the process and seekdb depends on the heartbeat to work normally. So we provide a debug sync mechanism to solve this problem. -The specific thread of SeekDB process will hang on the point if you add a debug sync point in the code, and then you can do something to debug the process, such as attach the process by gdb, or execute some SQL commands to get some information. +The specific thread of seekdb process will hang on the point if you add a debug sync point in the code, and then you can do something to debug the process, such as attach the process by gdb, or execute some SQL commands to get some information. > Debug Sync can work on release mode, so it is enabled on production environment. diff --git a/docs/developer-guide/en/ide-settings.md b/docs/developer-guide/en/ide-settings.md index dfa7c907c..e134ba890 100644 --- a/docs/developer-guide/en/ide-settings.md +++ b/docs/developer-guide/en/ide-settings.md @@ -5,11 +5,11 @@ title: Set up an IDE # Abstract -In order to easily read the code of SeekDB, we suggest using an IDE that can easily index the symbols of OceanBase SeekDB. On Windows, we recommend `Source Insight`; on Mac or Linux, we recommend `VSCode + ccls` to read the OceanBase code. Since `Source Insight` is very easy to use, this document skips the introduction on how to use it. +In order to easily read the code of seekdb, we suggest using an IDE that can easily index the symbols of OceanBase seekdb. On Windows, we recommend `Source Insight`; on Mac or Linux, we recommend `VSCode + ccls` to read the OceanBase code. Since `Source Insight` is very easy to use, this document skips the introduction on how to use it. -This document introduces how to set up `VSCode + ccls`, which is very convenient for reading the code of SeekDB. [ccls](https://github.com/MaskRay/ccls) is based on [cquery](https://github.com/jacobdufault/cquery), which is one of C/C++/Objective-C [LSP](https://en.wikipedia.org/wiki/Language_Server_Protocol)s (In one word, LSP is used to provide programming language-specific features like code completion, syntax highlighting and marking of warnings and errors, as well as refactoring routines). +This document introduces how to set up `VSCode + ccls`, which is very convenient for reading the code of seekdb. [ccls](https://github.com/MaskRay/ccls) is based on [cquery](https://github.com/jacobdufault/cquery), which is one of C/C++/Objective-C [LSP](https://en.wikipedia.org/wiki/Language_Server_Protocol)s (In one word, LSP is used to provide programming language-specific features like code completion, syntax highlighting and marking of warnings and errors, as well as refactoring routines). -The number of SeekDB code is pretty huge and SeekDB can't be compiled under Mac or Windows, so we recommend that download the code on the remote server, and start VSCode to access the code under the remote server. +The number of seekdb code is pretty huge and seekdb can't be compiled under Mac or Windows, so we recommend that download the code on the remote server, and start VSCode to access the code under the remote server. # Config ccls on Remote Server @@ -21,7 +21,7 @@ The following `/path/to` just means the path example, please replace it with you In the C/C++ LSP domain, the famous tools are clangd and ccls. Here we recommend ccls, because: 1. The speed of building index of ccls is slower than that of clangd, but after building, the speed of accessing index of ccls is faster than that of clangd. -2. Unity building is not supported by clangd, but SeekDB is built in unity mode, which causes clangd to fail to build index through compile_commands.json. +2. Unity building is not supported by clangd, but seekdb is built in unity mode, which causes clangd to fail to build index through compile_commands.json. # ccls Installation @@ -106,12 +106,12 @@ Password need to be input everytime. If you want to skip this action, please con ## C/C++ Plugin -We do **not** recommend using C/C++ plugins as they do not provide good indexing capabilities for SeekDB, and they are not compatible with the ccls plugin. +We do **not** recommend using C/C++ plugins as they do not provide good indexing capabilities for seekdb, and they are not compatible with the ccls plugin. C/C++ plugin can be download and installed in VSCode extension store in the case of simple scenarios: ![cpp plugins](images/ide-settings-cpp-plugins.png) -C/C++ plugin can automatically code completion and syntax highlighting, but this plugin failed to build index for SeekDB, it is hard to jump the symbol of SeekDB. +C/C++ plugin can automatically code completion and syntax highlighting, but this plugin failed to build index for seekdb, it is hard to jump the symbol of seekdb. ## ccls Plugin diff --git a/docs/developer-guide/en/logging.md b/docs/developer-guide/en/logging.md index a7448268e..6380bac1d 100644 --- a/docs/developer-guide/en/logging.md +++ b/docs/developer-guide/en/logging.md @@ -2,11 +2,11 @@ title: System Log --- -# OceanBase SeekDB System Log Introduction +# OceanBase seekdb System Log Introduction ## Introduction -This document mainly introduces the system logs of Oceanbase SeekDB, including the classification and level of the log, how to output logs in the program, and the details of some log implementation. +This document mainly introduces the system logs of Oceanbase seekdb, including the classification and level of the log, how to output logs in the program, and the details of some log implementation. ## System Log Introduction @@ -38,14 +38,14 @@ There are 7 parameters related to syslog, which are dynamically effective, that ## Log File Recycle -SeekDB's log can be configured with the upper limit of the number of files to prevent the log file from occupying too much disk space. +seekdb's log can be configured with the upper limit of the number of files to prevent the log file from occupying too much disk space. -If `enable_syslog_recycle = true` and `max_syslog_file_count > 0`, the number of each type log files can not exceed `max_syslog_file_count`. SeekDB will detect and delete old log files periodically. +If `enable_syslog_recycle = true` and `max_syslog_file_count > 0`, the number of each type log files can not exceed `max_syslog_file_count`. seekdb will detect and delete old log files periodically. The new log files will print a special log at the beginning. The information contains the IP and ports of the current node, version number, and some system information. Refer to `ObLogger::log_new_file_info` for more details. ``` -[2023-12-26 13:15:58.612579] INFO New syslog file info: [address: "127.0.0.1:2882", observer version: OceanBase SeekDB 1.0.0.0, revision: 101010012023111012-2f6924cd5a576f09d6e7f212fac83f1a15ff531a, sysname: Linux, os release: 3.10.0-327.ali2019.alios7.x86_64, machine: x86_64, tz GMT offset: 08:00] +[2023-12-26 13:15:58.612579] INFO New syslog file info: [address: "127.0.0.1:2882", observer version: OceanBase seekdb 1.0.0.0, revision: 101010012023111012-2f6924cd5a576f09d6e7f212fac83f1a15ff531a, sysname: Linux, os release: 3.10.0-327.ali2019.alios7.x86_64, machine: x86_64, tz GMT offset: 08:00] ``` ## Log Level @@ -69,7 +69,7 @@ Similar to the common system, Oceanbase also provides log macro to print differe There are three ways to adjust the log level: -- When the SeekDB process starts, it reads the log level config from configuration file or command line parameters. The configuration item name is `syslog_level`; +- When the seekdb process starts, it reads the log level config from configuration file or command line parameters. The configuration item name is `syslog_level`; - After startup, you can also connect through the MySQL client and execute the SQL command `alter system set syslog_level='DEBUG'`; - Modify the log level when the request is executed through the SQL Hint. For example `select /*+ log_level("ERROR") */ * from foo;`. This method is only effective for the current SQL request related logs. @@ -170,9 +170,9 @@ A log mainly contains the following parts: For developers, we only need to care about how to output our object information. Usually we write `K(obj)` to output the information we want in the log. Below are some details。 -In order to avoid some errors in format string, SeekDB uses automatic recognition of types and then serialization to solve this problem. Any parameter in the log will be identified as multiple Key Value pairs, where Key is the name of the field to be printed and Value is the value of the field. For example, `"consistency_level_in_plan_ctx", plan_ctx->get_consistency_level()` in the above example prints the name and value of a field. SeekDB automatically recognizes the type of Value and converts it to a string. The final output in the log may be "consistency_level_in_plan_ctx=3". +In order to avoid some errors in format string, seekdb uses automatic recognition of types and then serialization to solve this problem. Any parameter in the log will be identified as multiple Key Value pairs, where Key is the name of the field to be printed and Value is the value of the field. For example, `"consistency_level_in_plan_ctx", plan_ctx->get_consistency_level()` in the above example prints the name and value of a field. seekdb automatically recognizes the type of Value and converts it to a string. The final output in the log may be "consistency_level_in_plan_ctx=3". -Because most logs print the original name and value of the specified object, SeekDB provides some macros to simplify the operation of printing logs. The most commonly used one is `K`. Taking the above example `K(ret)`, its expansion in the code is: +Because most logs print the original name and value of the specified object, seekdb provides some macros to simplify the operation of printing logs. The most commonly used one is `K`. Taking the above example `K(ret)`, its expansion in the code is: ```cpp "ret", ret @@ -183,7 +183,7 @@ The final information in the log is: ret=-5595 ``` -SeekDB also provides some other macros, which are used in different scenarios. +seekdb also provides some other macros, which are used in different scenarios. > Log parameter macro definitions can be found in the `ob_log_module.h` file. @@ -191,7 +191,7 @@ SeekDB also provides some other macros, which are used in different scenarios. | ------ | --------------- | ----------- | | K | K(ret) | After expansion, it is `"ret", ret`. The parameter can be a simple value or an ordinary object | | K_ | K_(consistency_level) | After expansion, it is `"consistency_level", consistency_level_`. Different from K, the `_` suffix will be automatically added after the expanded Value, which is used for printing class member variables. | -| KR | KR(ret) | After expansion, it is `"ret", ret, "ret", common::ob_error_name(ret)`. This macro is for the convenience of printing error code and error code name. In SeekDB, `ret` is usually used as the return value of a function, and each return value has a corresponding string description. `ob_error_name` can get the string description corresponding to the error code. Note that this macro can only be used in non-lib code | +| KR | KR(ret) | After expansion, it is `"ret", ret, "ret", common::ob_error_name(ret)`. This macro is for the convenience of printing error code and error code name. In seekdb, `ret` is usually used as the return value of a function, and each return value has a corresponding string description. `ob_error_name` can get the string description corresponding to the error code. Note that this macro can only be used in non-lib code | | KCSTRING/
KCSTRING_ | KCSTRING(consistency_level_name) | After expansion, it is `"consistency_level_name", consistency_level_name`. This macro is used to print C-formatted strings. Since a variable of type `const char *` does not necessarily represent a string in C++, such as a binary buffer, when printing the value of this variable, if it is printed as a C string, an illegal memory access error will occur, so this macro has been added to explicitly print C strings | | KP/KP_ | KP(plan) | After expansion, it is `"plan", plan`, where `plan` is a pointer. This macro will print out the hexadecimal value of a pointer | | KPC/KPC_ | KPC(session) | The input parameters are object pointers. If it is NULL, "NULL" will be output. Otherwise, the `to_string` method of the pointer will be called to output the string. | @@ -205,13 +205,13 @@ SeekDB also provides some other macros, which are used in different scenarios. ### How to Convert Value to String -SeekDB automatically identifies the type of value you want to print in the log and converts it to a string. For example, in the above example, `ret` is an `int` type variable, and `plan_ctx->get_consistency_level()` returns an `enum` type variable. Both variables will be converted to strings. +seekdb automatically identifies the type of value you want to print in the log and converts it to a string. For example, in the above example, `ret` is an `int` type variable, and `plan_ctx->get_consistency_level()` returns an `enum` type variable. Both variables will be converted to strings. -However, since SeekDB does not know how to convert an ordinary object into a string, the user needs to implement a `TO_STRING_KV` function to convert the object into a string. For example, in the above example, `snapshot` is an object of type `ObTxReadSnapshot`. This object implements the `TO_STRING_KV` function, so it can be printed directly. +However, since seekdb does not know how to convert an ordinary object into a string, the user needs to implement a `TO_STRING_KV` function to convert the object into a string. For example, in the above example, `snapshot` is an object of type `ObTxReadSnapshot`. This object implements the `TO_STRING_KV` function, so it can be printed directly. **Convert normal value to string** -SeekDB can automatically identify simple type values, such as `int`, `int64_t`, `double`, `bool`, `const char *`, etc., and convert them into strings. For enumeration types, they will be treated as numbers. For pointers, the pointer value will be output in hexadecimal format. +seekdb can automatically identify simple type values, such as `int`, `int64_t`, `double`, `bool`, `const char *`, etc., and convert them into strings. For enumeration types, they will be treated as numbers. For pointers, the pointer value will be output in hexadecimal format. **Convert class object to string** @@ -238,7 +238,7 @@ As you can see, in `TO_STRING_KV`, you can directly use a macro similar to print ### Log Module -SeekDB's logs are module-specific and can support sub-modules. For example, in the above example, `[SQL.EXE]` is a module, `SQL` is a main module, and `EXE` is a submodule. For the definition of the log module, please refer to the `LOG_MOD_BEGIN` and `DEFINE_LOG_SUB_MOD` related codes in the `ob_log_module.h` file. +seekdb's logs are module-specific and can support sub-modules. For example, in the above example, `[SQL.EXE]` is a module, `SQL` is a main module, and `EXE` is a submodule. For the definition of the log module, please refer to the `LOG_MOD_BEGIN` and `DEFINE_LOG_SUB_MOD` related codes in the `ob_log_module.h` file. **How does the log module output to the log?** @@ -249,7 +249,7 @@ Normally, we just use macros like `LOG_WARN` to print logs, and different module **How to specify module name explicitly?** -The above method is indeed a bit inflexible. SeekDB has another way to specify the module name, which is to use the macro `OB_MOD_LOG` or `OB_SUB_MOD_LOG`. The usage of these two macros is similar to `LOG_WARN`, except that there are additional module parameters and log levels: +The above method is indeed a bit inflexible. seekdb has another way to specify the module name, which is to use the macro `OB_MOD_LOG` or `OB_SUB_MOD_LOG`. The usage of these two macros is similar to `LOG_WARN`, except that there are additional module parameters and log levels: ```cpp OB_MOD_LOG(parMod, level, info_string, args...) @@ -258,7 +258,7 @@ OB_SUB_MOD_LOG(parMod, subMod, level, info_string, args...) **Set the module's log level** -In addition to setting the global and current thread log levels, SeekDB can also adjust the log level of a certain module. Currently, you can use `SQL HINT` to modify the log level of a module when executing a request, for example: +In addition to setting the global and current thread log levels, seekdb can also adjust the log level of a certain module. Currently, you can use `SQL HINT` to modify the log level of a module when executing a request, for example: ```sql select /*+ log_level("SHARE.SCHEMA:ERROR") */ * from foo; @@ -268,26 +268,26 @@ Where `SHARE` is the main module, `SCHEMA` is the submodule, and `ERROR` is the ### Log Time -SeekDB's log time is the number of microseconds in the current local time. -Since converting a timestamp into a string is a time-consuming task, SeekDB caches the timestamp conversion to speed up the process. For details, please refer to the `ob_fast_localtime` function. +seekdb's log time is the number of microseconds in the current local time. +Since converting a timestamp into a string is a time-consuming task, seekdb caches the timestamp conversion to speed up the process. For details, please refer to the `ob_fast_localtime` function. ### Thread Identifier Currently, two information related to thread will be recorded: - Thread ID: the information returned by the system call `__NR_gettid` (the system call is relatively inefficient, and this value will be cached); -- Thread name: The thread name field may contain the tenant ID, thread pool type, and thread pool index. The thread name of SeekDB is set through the `set_thread_name` function and will also be displayed in the `top` command. +- Thread name: The thread name field may contain the tenant ID, thread pool type, and thread pool index. The thread name of seekdb is set through the `set_thread_name` function and will also be displayed in the `top` command. > NOTE：The thread name is determined by the created thread. Since the tenant of the created thread may be different from the tenant of subsequent runs of this thread, the tenant in the thread name may be incorrect. ### Log Rate Limit -SeekDB supports two log rate limits: a common system log disk IO bandwidth limit and a WDIAG system log limit. +seekdb supports two log rate limits: a common system log disk IO bandwidth limit and a WDIAG system log limit. **System log bandwidth rate limit** -SeekDB will limit log output according to disk bandwidth. The log bandwidth rate limit does not limit the rate for different log levels. If the log rate is limited, the rate limit log may be printed with the keyword `REACH SYSLOG RATE LIMIT`. +seekdb will limit log output according to disk bandwidth. The log bandwidth rate limit does not limit the rate for different log levels. If the log rate is limited, the rate limit log may be printed with the keyword `REACH SYSLOG RATE LIMIT`. Rate limit log example: @@ -301,7 +301,7 @@ Please refer to the `check_tl_log_limiter` function for rate limiting code detai **WDIAG log rate limit** -SeekDB has implemented a current limit for WARN level logs. Each error code is limited to 200 logs per second by default. If the limit is exceeded, the current limiting log will be output, keyword `Throttled WDIAG logs in last second`. The current limiting threshold can be adjusted through the configuration item `diag_syslog_per_error_limit`. +seekdb has implemented a current limit for WARN level logs. Each error code is limited to 200 logs per second by default. If the limit is exceeded, the current limiting log will be output, keyword `Throttled WDIAG logs in last second`. The current limiting threshold can be adjusted through the configuration item `diag_syslog_per_error_limit`. Limiting log example: @@ -316,7 +316,7 @@ Limiting code reference `ObSyslogPerErrLimiter::do_acquire`。 ### Logs for DBA -There are also two types of special logs in SeekDB, LOG_DBA_WARN and LOG_DBA_ERROR, which correspond to WARN and ERROR logs respectively. Since the volume of SeekDB logs is extremely large, and most of them can only be understood by R&D personnel, it brings a certain burden to DBA operation and maintenance troubleshooting problems. Therefore, these two types of logs are added, hoping that the DBA can only focus on a small amount of these two types of logs to troubleshoot system problems. The logs output using LOG_WARN and LOG_ERROR are converted into WDIAG and EDIAG logs to help developers troubleshoot problems. +There are also two types of special logs in seekdb, LOG_DBA_WARN and LOG_DBA_ERROR, which correspond to WARN and ERROR logs respectively. Since the volume of seekdb logs is extremely large, and most of them can only be understood by R&D personnel, it brings a certain burden to DBA operation and maintenance troubleshooting problems. Therefore, these two types of logs are added, hoping that the DBA can only focus on a small amount of these two types of logs to troubleshoot system problems. The logs output using LOG_WARN and LOG_ERROR are converted into WDIAG and EDIAG logs to help developers troubleshoot problems. ### Output Prompt Information to the User Terminal @@ -340,7 +340,7 @@ Since `LOG_USER_XXX` provides fixed error information, if we want to output some ### Health Log -SeekDB will periodically output some internal status information, such as the memory information of each module and tenant, to the log to facilitate problem finding. This kind of log usually outputs multiple lines of data in one log, such as: +seekdb will periodically output some internal status information, such as the memory information of each module and tenant, to the log to facilitate problem finding. This kind of log usually outputs multiple lines of data in one log, such as: ```txt [2023-12-26 13:15:58.608131] INFO [LIB] print_usage (ob_tenant_ctx_allocator.cpp:176) [35582][MemDumpTimer][T0][Y0-0000000000000000-0-0] [lt=116] @@ -355,4 +355,4 @@ SeekDB will periodically output some internal status information, such as the me This kind of data can be helpful for finding historical issues. ### ERROR Log -For general errors that occur in the system, such as an exception when processing a certain request, logs will be output at WARN level. Only when the normal operation of the SeekDB process is affected, or if there is a serious problem, the log will be output at the ERROR level. Therefore, if a process exits abnormally or cannot be started, searching the ERROR log will more effectively find the cause of the problem. +For general errors that occur in the system, such as an exception when processing a certain request, logs will be output at WARN level. Only when the normal operation of the seekdb process is affected, or if there is a serious problem, the log will be output at the ERROR level. Therefore, if a process exits abnormally or cannot be started, searching the ERROR log will more effectively find the cause of the problem. diff --git a/docs/developer-guide/en/memory.md b/docs/developer-guide/en/memory.md index 1a4652604..27e46bb06 100644 --- a/docs/developer-guide/en/memory.md +++ b/docs/developer-guide/en/memory.md @@ -3,7 +3,7 @@ title: Memory Management --- # Introduction -Memory management is one of the most important modules in any large C++ project. Since OceanBase SeekDB also needs to deal with the issue of multi-tenant memory resource isolation, SeekDB's memory management is more complicated than ordinary C++ projects. Generally, a good memory management module needs to consider the following issues: +Memory management is one of the most important modules in any large C++ project. Since OceanBase seekdb also needs to deal with the issue of multi-tenant memory resource isolation, seekdb's memory management is more complicated than ordinary C++ projects. Generally, a good memory management module needs to consider the following issues: - Easy to use. The designed interface must be understood and used by the container, otherwise the code will be difficult to read and maintain, and memory errors will be more likely to occur; - Efficient. An efficient memory allocator has a crucial impact on performance, especially in high-concurrency scenarios; @@ -13,14 +13,14 @@ For the multi-tenant model, the impact of memory management design mainly includ - Transparent interface design. How to make developers have no awareness or little need to care about the memory management of different tenants; - Efficient and accurate. Sufficient memory must be applied successfully, and tenant memory exhaustion must be detected in time, which is the most basic condition for multi-tenant memory management. -This article will introduce the commonly used memory allocation interfaces and memory management related idioms in SeekDB. For technical details of memory management, please refer to [Memory Management](https://open.oceanbase.com/blog/8501613072)( In Chinese). +This article will introduce the commonly used memory allocation interfaces and memory management related idioms in seekdb. For technical details of memory management, please refer to [Memory Management](https://open.oceanbase.com/blog/8501613072)( In Chinese). -# Common Interfaces and Methods of OceanBase SeekDB Memory Management -SeekDB provides different memory allocators for different scenarios. In addition, in order to improve program execution efficiency, there are some conventional implementations, such as reset/reuse, etc. +# Common Interfaces and Methods of OceanBase seekdb Memory Management +seekdb provides different memory allocators for different scenarios. In addition, in order to improve program execution efficiency, there are some conventional implementations, such as reset/reuse, etc. ## ob_malloc -SeekDB has developed a set of libc-style interface functions ob_malloc/ob_free/ob_realloc. This set of interfaces will dynamically apply for memory blocks of size based on tenant_id, ctx_id, label and other attributes, and mark the memory blocks to determine ownership. This not only facilitates multi-tenant resource management, but is also very helpful in diagnosing memory problems. +seekdb has developed a set of libc-style interface functions ob_malloc/ob_free/ob_realloc. This set of interfaces will dynamically apply for memory blocks of size based on tenant_id, ctx_id, label and other attributes, and mark the memory blocks to determine ownership. This not only facilitates multi-tenant resource management, but is also very helpful in diagnosing memory problems. ob_malloc will index to the corresponding ObTenantCtxAllocator based on tenant_id and ctx_id, and ObTenantCtxAllocator will allocate memory according to the current tenant context. ob_free uses offset operation to find the object allocator corresponding to the memory to be released, and then returns the memory to the memory pool. @@ -53,13 +53,13 @@ Similar to ob_malloc, OB_NEW provides a set of "C++" interfaces that call the ob The design feature is to allocate release multiple times and only release once. Only reset or destruction can truly release the memory. The memory allocated before will not have any effect even if `free` is actively called. -ObArenaAllocator is suitable for scenarios where many small memory allocates are released in a short period of time. For example, in a SQL request, many small block memories will be frequently allocated, and the life cycle of these small memories will last for the entire request period. Usually, the processing time of an SQL request is also very short. This memory allocation method is very effective for small memory and avoiding memory leaks. In SeekDB's code, don't be surprised if you see there is only apply for memory but cannot find a place to release it. +ObArenaAllocator is suitable for scenarios where many small memory allocates are released in a short period of time. For example, in a SQL request, many small block memories will be frequently allocated, and the life cycle of these small memories will last for the entire request period. Usually, the processing time of an SQL request is also very short. This memory allocation method is very effective for small memory and avoiding memory leaks. In seekdb's code, don't be surprised if you see there is only apply for memory but cannot find a place to release it. > Code reference `page_arena.h` ## ObMemAttr Introduction -SeekDB uses `ObMemAttr` to mark a section of memory. +seekdb uses `ObMemAttr` to mark a section of memory. ```cpp struct ObMemAttr @@ -80,7 +80,7 @@ Memory allocation management perform resource statistics and restrictions based **label** -At the beginning, SeekDB uses a predefined method to create memory labels for each module. However, as the amount of code increases, the method of predefined labels is not suitable. Currently, ObLabel is constructed directly using constant strings. When using ob_malloc, you can also directly pass in a constant string as the ObLabel parameter, such as `buf = ob_malloc(disk_addr.size_, "ReadBuf");`. +At the beginning, seekdb uses a predefined method to create memory labels for each module. However, as the amount of code increases, the method of predefined labels is not suitable. Currently, ObLabel is constructed directly using constant strings. When using ob_malloc, you can also directly pass in a constant string as the ObLabel parameter, such as `buf = ob_malloc(disk_addr.size_, "ReadBuf");`. **ctx_id** @@ -106,7 +106,7 @@ Currently, two memory allocation priorities are supported, Normal and High. The ## init/destroy/reset/reuse -Caching is one of the important methods to improve program performance. Object reuse is also a way of caching. On the one hand, it reduces the frequency of memory allocate and release, and on the other hand, it can reduce some construction and destruction overhead. There is a lot of object reuse in SeekDB, and some conventions have been formed, such as the reset and reuse functions. +Caching is one of the important methods to improve program performance. Object reuse is also a way of caching. On the one hand, it reduces the frequency of memory allocate and release, and on the other hand, it can reduce some construction and destruction overhead. There is a lot of object reuse in seekdb, and some conventions have been formed, such as the reset and reuse functions. **reset** @@ -118,7 +118,7 @@ Compared with reset, it is more lightweight. Try not to release some expensive r **init/destroy** -There are two other common interfaces in SeekDB: `init` and `destroy`. `init` is used to initizalize object and `destory` to release resources. Only do some very lightweight initialization work in the constructor, such as initializing the pointer to `nullptr`. +There are two other common interfaces in seekdb: `init` and `destroy`. `init` is used to initizalize object and `destory` to release resources. Only do some very lightweight initialization work in the constructor, such as initializing the pointer to `nullptr`. ## SMART_VAR/HEAP_VAR diff --git a/docs/developer-guide/en/mysqltest.md b/docs/developer-guide/en/mysqltest.md index c4c3baae6..68180fe53 100644 --- a/docs/developer-guide/en/mysqltest.md +++ b/docs/developer-guide/en/mysqltest.md @@ -1,23 +1,23 @@ # Running mysqltest by obd.sh -When using obd.sh to run the mysqltest test, you need to use the OceanBase SeekDB database deployed through obd.sh. This article uses examples to introduce how to use obd.sh to deploy the SeekDB database and run the mysqltest test starting from compiling the source code. +When using obd.sh to run the mysqltest test, you need to use the OceanBase seekdb database deployed through obd.sh. This article uses examples to introduce how to use obd.sh to deploy the seekdb database and run the mysqltest test starting from compiling the source code. ## Background -In order to simplify the operating steps for developers and reduce their understanding costs, we encapsulate some OBD commands into the obd.sh script and store the script in the oceanbase/tools/deploy directory of the SeekDB source code. This article runs the mysqltest test by calling the [obd test mysqltest](https://www.oceanbase.com/docs/community-obd-cn-10000000002048173) commands in OBD. +In order to simplify the operating steps for developers and reduce their understanding costs, we encapsulate some OBD commands into the obd.sh script and store the script in the oceanbase/tools/deploy directory of the seekdb source code. This article runs the mysqltest test by calling the [obd test mysqltest](https://www.oceanbase.com/docs/community-obd-cn-10000000002048173) commands in OBD. ## Concepts -mysqltest is a test in the SeekDB database access test. Simply put, it takes the written case file as input and compares the output of the database with the expected output. The cases tested by mysqltest in the SeekDB database are all located in the `tools/deploy/mysqltest` directory of the SeekDB source code. +mysqltest is a test in the seekdb database access test. Simply put, it takes the written case file as input and compares the output of the database with the expected output. The cases tested by mysqltest in the seekdb database are all located in the `tools/deploy/mysqltest` directory of the seekdb source code. `case` is the smallest execution unit of mysqltest. A `case` contains at least one test file and one result file. Classifying cases forms a `suite`, and a `suite` is a collection of cases. ## Steps -### Step 1: Compile OceanBase SeekDB database from source code +### Step 1: Compile OceanBase seekdb database from source code -Please refer to [build-and-run](./build-and-run.md) to compile the SeekDB database from source code. +Please refer to [build-and-run](./build-and-run.md) to compile the seekdb database from source code. ### Step 2: Run mysqltest test diff --git a/docs/developer-guide/en/toolchain.md b/docs/developer-guide/en/toolchain.md index 665a63f19..6a838f7b4 100644 --- a/docs/developer-guide/en/toolchain.md +++ b/docs/developer-guide/en/toolchain.md @@ -1,6 +1,6 @@ # Install toolchain -To build OceanBase SeekDB from source code, you need to install the C++ toolchain in your development environment first. If the C++ toolchain is not installed yet, you can follow the instructions in this document for installation. +To build OceanBase seekdb from source code, you need to install the C++ toolchain in your development environment first. If the C++ toolchain is not installed yet, you can follow the instructions in this document for installation. ## Supported OS @@ -26,7 +26,7 @@ Below is the OS compatibility list: > **Note**: > -> Other Linux distributions _may_ work. If you verify that OceanBase SeekDB can compile and deploy on a distribution except ones listed above, feel free to submit a pull request to add it. +> Other Linux distributions _may_ work. If you verify that OceanBase seekdb can compile and deploy on a distribution except ones listed above, feel free to submit a pull request to add it. ## Installation diff --git a/docs/developer-guide/en/unittest.md b/docs/developer-guide/en/unittest.md index fc320cba8..2d77a1b13 100644 --- a/docs/developer-guide/en/unittest.md +++ b/docs/developer-guide/en/unittest.md @@ -2,13 +2,13 @@ ## How to Build and Run All Unit Tests -[OceanBase SeekDB](https://github.com/oceanbase/seekdb) has two unittest directories. +[OceanBase seekdb](https://github.com/oceanbase/seekdb) has two unittest directories. - `unittest`: These are the main unit test cases, and they test the code in the `src` directory. - `deps/oblib/unittest`: Test cases for oblib. -First, you should build `unittest`. Enter the `unittest` directory in the build directory and build explicitly. When you build the SeekDB project, it doesn't build the unit tests by default. For example: +First, you should build `unittest`. Enter the `unittest` directory in the build directory and build explicitly. When you build the seekdb project, it doesn't build the unit tests by default. For example: ```bash bash build.sh --init --make # init and build a debug mode project @@ -33,9 +33,9 @@ find . -name "test_chunk_row_store" ## How to Write Unit Tests -As a C++ project, [OceanBase SeekDB](https://github.com/oceanbase/seekdb) uses [Google Test](https://github.com/google/googletest) as the unit test framework. +As a C++ project, [OceanBase seekdb](https://github.com/oceanbase/seekdb) uses [Google Test](https://github.com/google/googletest) as the unit test framework. -SeekDB uses `test_xxx.cpp` as the unit test file name. Create a `test_xxx.cpp` file and add the file name to the specific `CMakeLists.txt` file. +seekdb uses `test_xxx.cpp` as the unit test file name. Create a `test_xxx.cpp` file and add the file name to the specific `CMakeLists.txt` file. In the `test_xxx.cpp` file, add the header file `#include ` and the main function below. diff --git a/docs/developer-guide/zh/README.md b/docs/developer-guide/zh/README.md index 7971367ba..a17bb259a 100644 --- a/docs/developer-guide/zh/README.md +++ b/docs/developer-guide/zh/README.md @@ -1,9 +1,9 @@ -# OceanBase SeekDB 开发者手册 +# OceanBase seekdb 开发者手册 ## 介绍 -* **面向人群** 手册的目标受众是OceanBase SeekDB的贡献者，无论是新人还是老手。 -* **目标** 手册的目标是帮助贡献者成为OceanBase SeekDB的专家，熟悉其设计和实现，从而能够在现实世界中流畅地使用它以及深入开发OceanBase SeekDB本身。 +* **面向人群** 手册的目标受众是OceanBase seekdb的贡献者，无论是新人还是老手。 +* **目标** 手册的目标是帮助贡献者成为OceanBase seekdb的专家，熟悉其设计和实现，从而能够在现实世界中流畅地使用它以及深入开发OceanBase seekdb本身。 ## 手册结构 @@ -11,17 +11,17 @@ ### 第一部分：开发环境搭建 -这部分帮助新手快速搭建开发环境，开始使用SeekDB。 +这部分帮助新手快速搭建开发环境，开始使用seekdb。 1. [安装工具链](toolchain.md) - 安装C++编译工具链 -2. [获取代码，编译运行](build-and-run.md) - 克隆代码、编译和运行SeekDB +2. [获取代码，编译运行](build-and-run.md) - 克隆代码、编译和运行seekdb 3. [配置IDE](ide-settings.md) - 配置VSCode + ccls进行代码阅读和开发 ### 第二部分：开发规范与实践 -了解SeekDB的编程规范和开发习惯，确保代码风格一致。 +了解seekdb的编程规范和开发习惯，确保代码风格一致。 -1. [编程惯例](coding-convention.md) - SeekDB特有的编程习惯和约定（快速入门） +1. [编程惯例](coding-convention.md) - seekdb特有的编程习惯和约定（快速入门） 2. [编程规范](coding-standard.md) - 详细的C++编码规范和约束（深入参考） ### 第三部分：测试与调试 @@ -30,18 +30,18 @@ 1. [编写并运行单元测试](unittest.md) - 使用Google Test编写和运行单元测试 2. [运行MySQL测试](mysqltest.md) - 运行mysqltest集成测试 -3. [调试](debug.md) - 使用GDB、日志等方式调试SeekDB +3. [调试](debug.md) - 使用GDB、日志等方式调试seekdb ### 第四部分：核心系统设计 -深入理解SeekDB的核心设计和实现。 +深入理解seekdb的核心设计和实现。 -1. [内存管理](memory.md) - SeekDB的内存管理机制和多租户内存隔离 +1. [内存管理](memory.md) - seekdb的内存管理机制和多租户内存隔离 2. [日志系统](logging.md) - 日志的使用方法和实现细节 -3. [基础数据结构](container.md) - SeekDB提供的容器类（替代STL） +3. [基础数据结构](container.md) - seekdb提供的容器类（替代STL） ### 第五部分：贡献代码 -参与SeekDB开发的完整流程。 +参与seekdb开发的完整流程。 -1. [提交代码和Pull Request](contributing.md) - 如何贡献代码到SeekDB项目 +1. [提交代码和Pull Request](contributing.md) - 如何贡献代码到seekdb项目 diff --git a/docs/developer-guide/zh/build-and-run.md b/docs/developer-guide/zh/build-and-run.md index a174971f6..7a9629d08 100644 --- a/docs/developer-guide/zh/build-and-run.md +++ b/docs/developer-guide/zh/build-and-run.md @@ -1,6 +1,6 @@ # 编译与运行 -本文档介绍如何获取 OceanBase SeekDB 源代码、编译项目以及运行 SeekDB 实例。 +本文档介绍如何获取 OceanBase seekdb 源代码、编译项目以及运行 seekdb 实例。 ## 前置条件 @@ -27,7 +27,7 @@ cd seekdb ## 编译项目 -SeekDB 支持两种编译模式：Debug 和 Release。推荐开发时使用 Debug 模式，生产环境使用 Release 模式。 +seekdb 支持两种编译模式：Debug 和 Release。推荐开发时使用 Debug 模式，生产环境使用 Release 模式。 ### Debug 模式 @@ -53,7 +53,7 @@ bash build.sh release --init --make ## 运行实例 -编译完成后，可以使用 `obd.sh` 工具部署一个 SeekDB 实例。 +编译完成后，可以使用 `obd.sh` 工具部署一个 seekdb 实例。 ### 部署步骤 @@ -73,11 +73,11 @@ bash build.sh release --init --make 部署完成后，可以通过查看 `./tools/deploy/single.yaml` 文件中的 `mysql_port` 配置项来确认监听端口。 -> **默认端口**：如果使用 root 用户部署，SeekDB 服务程序默认监听 10000 端口。下文示例基于此默认端口。 +> **默认端口**：如果使用 root 用户部署，seekdb 服务程序默认监听 10000 端口。下文示例基于此默认端口。 ## 连接数据库 -部署成功后，可以使用以下方式连接 SeekDB： +部署成功后，可以使用以下方式连接 seekdb： ### 使用 MySQL 客户端 @@ -104,10 +104,10 @@ mysql -uroot -h127.0.0.1 -P10000 ./tools/deploy/obd.sh destroy --rm -n single ``` -该命令会停止运行中的 SeekDB 实例并清理相关资源。 +该命令会停止运行中的 seekdb 实例并清理相关资源。 ## 下一步 - [编写单元测试](unittest.md) - 学习如何编写和运行单元测试 -- [调试方法](debug.md) - 了解如何调试 SeekDB -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程规范 +- [调试方法](debug.md) - 了解如何调试 seekdb +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程规范 diff --git a/docs/developer-guide/zh/coding-convention.md b/docs/developer-guide/zh/coding-convention.md index 5e285d4ce..e7850c454 100644 --- a/docs/developer-guide/zh/coding-convention.md +++ b/docs/developer-guide/zh/coding-convention.md @@ -2,13 +2,13 @@ title: 编程惯例 --- -OceanBase SeekDB 编程惯例 +OceanBase seekdb 编程惯例 -OceanBase SeekDB 是一个发展了十几年的、包含几百万行C++代码的巨型工程，它已经有了很多自己特有的编程习惯，这里介绍一些首次接触SeekDB源码同学一些需要注意的事项，也可以让大家更方便的阅读SeekDB源码。更详细的内容可以参考[OceanBase SeekDB C++编程规范](coding_standard.md)。 +OceanBase seekdb 是一个基于发展了十几年的、包含几百万行C++代码的巨型工程 OceanBase 演化而来，它已经有了很多自己特有的编程习惯，这里介绍一些首次接触seekdb源码同学一些需要注意的事项，也可以让大家更方便的阅读seekdb源码。更详细的内容可以参考[OceanBase seekdb C++编程规范](coding-standard.md)。 # 命名习惯 ## 文件命名 -SeekDB中代码文件名都以`ob_`开头。但也有一些陈旧的例外文件。 +seekdb中代码文件名都以`ob_`开头。但也有一些陈旧的例外文件。 ## 类命名 类都以`Ob`开头，也有一些陈旧类的意外。 @@ -18,10 +18,10 @@ SeekDB中代码文件名都以`ob_`开头。但也有一些陈旧的例外文件 # 函数编程习惯 ## 禁止使用STL容器 -由于SeekDB支持多租户资源隔离，为了方便控制内存，SeekDB禁止使用STL、boost等容器。同时，SeekDB提供了自己实现的容器，比如 `ObSEArray` 等。 +由于seekdb支持多租户资源隔离，为了方便控制内存，seekdb禁止使用STL、boost等容器。同时，seekdb提供了自己实现的容器，比如 `ObSEArray` 等。 ## 单入口单出口 -强制要求所有函数在末尾返回，禁止中途调用return、goto、exit等全局跳转指令。这一条也是所有首次接触SeekDB代码的人最迷惑的地方。 +强制要求所有函数在末尾返回，禁止中途调用return、goto、exit等全局跳转指令。这一条也是所有首次接触seekdb代码的人最迷惑的地方。 为了实现这一要求，代码中会出现很多 `if/else if` ，并且在 `for` 循环中存在 `OB_SUCC(ret)` 等多个不那么直观的条件判断。同时为了减少嵌套，会使用宏 `FALSE_IT` 执行某些语句。比如 ```cpp @@ -74,7 +74,7 @@ int64_t get_capacity(); 或者类似的简单判断的函数不需要返回int错误码。 ## 需要判断所有函数值与函数参数有效性 -SeekDB 要求只要函数有返回值，就必须对返回值做检测，做到“能检就检”。对于函数参数，特别是指针，在使用前都必须检查其有效性。 +seekdb 要求只要函数有返回值，就必须对返回值做检测，做到“能检就检”。对于函数参数，特别是指针，在使用前都必须检查其有效性。 比如： ```cpp int ObDDLServerClient::abort_redef_table(const obrpc::ObAbortRedefTableArg &arg, sql::ObSQLSessionInfo *session) @@ -97,10 +97,10 @@ int ObDDLServerClient::abort_redef_table(const obrpc::ObAbortRedefTableArg &arg, # 一些约定函数接口 ## init/destroy -SeekDB 要求在构造函数中，仅实现一些非常轻量级的数据初始化工作，比如变量初始化为0，指针初始化为nullptr等。因为构造函数中，不太容易处理一些复杂的异常场景，并且无法给出返回值。SeekDB绝大多数的类都有 init 函数，通常在构造函数之后执行，并且拥有int错误码作为返回值。这里做一些比较复杂的初始化工作。相对应的，通常也会提供destroy函数做资源销毁工作。 +seekdb 要求在构造函数中，仅实现一些非常轻量级的数据初始化工作，比如变量初始化为0，指针初始化为nullptr等。因为构造函数中，不太容易处理一些复杂的异常场景，并且无法给出返回值。seekdb绝大多数的类都有 init 函数，通常在构造函数之后执行，并且拥有int错误码作为返回值。这里做一些比较复杂的初始化工作。相对应的，通常也会提供destroy函数做资源销毁工作。 ## reuse/reset -内存缓存是提高性能非常有效的手段。SeekDB 很多类都会有reuse/reset接口，以方便某个对象后续重用。reuse 通常表示轻量级的清理工作，而reset会做更多的资源清理工作。但是需要看具体实现类，不能一概而论。 +内存缓存是提高性能非常有效的手段。seekdb 很多类都会有reuse/reset接口，以方便某个对象后续重用。reuse 通常表示轻量级的清理工作，而reset会做更多的资源清理工作。但是需要看具体实现类，不能一概而论。 ## 操作符重载 C++ 提供了非常方便编写程序的运算符重载功能，但是这些重载往往会带来很多负担，使得代码难以阅读、功能误用。比如运算符重载可能会导致程序员不知情的情况下出现类型隐式转换、或者看起来一个简单的操作却有比较高的开销。 另外，要尽量避免使用 `operator=` ，尽量以`deep_copy`、`shallow_copy`的方式实现对象的复制。 diff --git a/docs/developer-guide/zh/coding-standard.md b/docs/developer-guide/zh/coding-standard.md index dbf690225..c88460b74 100644 --- a/docs/developer-guide/zh/coding-standard.md +++ b/docs/developer-guide/zh/coding-standard.md @@ -7,7 +7,7 @@ title: 编程规范 | 1 | 0.1 | 全文 | 初版 | 2025/11/7 | # 1 引言 -本编码规范适用于蚂蚁金服OceanBase SeekDB项目，给出了一些编码约束，并定义了编码风格。SeekDB项目中，测试代码必须遵守本文档的编码风格，建议测试代码也同时遵守本文档的编码约束；其他代码必须遵守本文档的编码约束和编码风格。 +本编码规范适用于蚂蚁金服OceanBase seekdb项目，给出了一些编码约束，并定义了编码风格。seekdb项目中，测试代码必须遵守本文档的编码风格，建议测试代码也同时遵守本文档的编码约束；其他代码必须遵守本文档的编码约束和编码风格。 本编码规范致力于书写出通俗易懂、减少陷阱、格式统一的C/C++代码，因此： @@ -20,14 +20,14 @@ title: 编程规范 # 2 目录和文件 ## 2.1 目录结构 -SeekDB系统的子目录说明如下： +seekdb系统的子目录说明如下： - src：存放源代码，包含头文件和实现文件 - unittest：存放单元测试代码和开发人员编写的小规模集成测试代码 - tests：存放测试团队的测试框架和用例 - tools：存放外部工具 - doc：存放文档 - rpm：存放rpm spec文件 -- script：存放SeekDB的运维脚本 +- script：存放seekdb的运维脚本 C代码的实现文件命名为.c，头文件命名为.h，C++代码的实现文件命名为.cpp，头文件命名为.h。原则上头文件和实现文件必须一一对应，src下的目录和unittest下的目录一一对应。所有文件命名统一使用全部英文小写字母，单词之间使用'_'分割。 例如，src下的common目录有一个头文件ob_schema.h和实现文件ob_schema.cpp，相应地，在unittest目录下也有一个common目录，其中有一个名字叫做test_schema.cpp的单元测试文件。 @@ -93,7 +93,7 @@ C代码的实现文件命名为.c，头文件命名为.h，C++代码的实现文 类的构造函数和析构函数容易引起误解。它们可能看起来很短，不过要当心可能隐藏一些行为，如“偷偷地”执行了基类或成员对象的构造和析构函数。 ## 2.7 #include的路径和顺序 -项目内头文件应该按照项目目录树结构引入，不要使用特殊路径，类似'.'，'..'等。建议包含头文件的顺序为本文件对应的头文件，系统c头文件，系统c++头文件，其它库头文件（libeasy，tbsys），SeekDB内部其它头文件，避免出现多重包含。其中，系统c头文件用尖括号，末尾加.h，系统C++头文件用尖括号，末尾不加.h，其它情况用引号，例如 +项目内头文件应该按照项目目录树结构引入，不要使用特殊路径，类似'.'，'..'等。建议包含头文件的顺序为本文件对应的头文件，系统c头文件，系统c++头文件，其它库头文件（libeasy，tbsys），seekdb内部其它头文件，避免出现多重包含。其中，系统c头文件用尖括号，末尾加.h，系统C++头文件用尖括号，末尾不加.h，其它情况用引号，例如 ```cpp #include ， @@ -129,11 +129,11 @@ C代码的实现文件命名为.c，头文件命名为.h，C++代码的实现文 3.通过define保护避免头文件被多重包含。 4.通过前置声明降低编译依赖，防止修改一个文件引发多米诺效应。 5.内联函数的合理使用可以提高执行代码效率。 -6.项目内文件的include路径为相对路径，include顺序为：本文件对应的头文件，系统c头文件，系统c++头文件，其它库头文件（Libeasy，tbsys），SeekDB 内部其它头文件。 +6.项目内文件的include路径为相对路径，include顺序为：本文件对应的头文件，系统c头文件，系统c++头文件，其它库头文件（Libeasy，tbsys），seekdb 内部其它头文件。 # 3 作用域 ## 3.1 命名空间 -SeekDB源代码中的所有变量、函数以及类都通过命名空间区分开来，命名空间和代码所处的目录一一对应。例如，`src/common`目录下的`ob_schema.h`对应的命名空间为 `oceanbase::common`。 +seekdb源代码中的所有变量、函数以及类都通过命名空间区分开来，命名空间和代码所处的目录一一对应。例如，`src/common`目录下的`ob_schema.h`对应的命名空间为 `oceanbase::common`。 ```cpp // .h文件 @@ -311,7 +311,7 @@ b.cpp &bbb=0x400798 ## 3.4 局部变量 在语句块开始处（由{}组成）声明变量，强制要求简单变量声明时就初始化。 -SeekDB认为需要在每个语句块（由{}组成）的开始处声明，这样的代码的可读性较好。另外，允许 `for (int +seekdb认为需要在每个语句块（由{}组成）的开始处声明，这样的代码的可读性较好。另外，允许 `for (int i = 0; i < 10; ++i)` (i在for循环开始处声明，相当于循环语句块的开头)这样的代码。如果声明变量和使用变量的地方相隔较远，说明语句块包含的代码过多，这往往意味着需要进行代码重构。 在循环体内声明变量，如果变量是一个对象，每次循环都要先后调用其构造函数和析构函数，每次循环也需要圧栈和弹栈，因此将这样的变量提取到循环外要高效得多。禁止在循环体内声明非简单变量（例如类变量），如果必须违反，请事先征得小组负责人的同意，并详细注释原因。出于代码可读性的考虑，允许在循环内声明引用。 @@ -802,7 +802,7 @@ if (OB_FAIL(ret)) { 当子类继承父类时，子类包含了父类的所有数据及操作定义。C++实践中，继承主要用于两种场景：实现继承，子类继承父类的实现代码；接口继承，子类继承父类的方法名称。对于实现继承，由于实现子类的代码在父类和子类间延展，要理解其实现变得更加困难，要谨慎使用。 -SeekDB里面也用到了多重继承，这种场景是很少见的，并且要求最多只有一个基类中包含实现，其他基类都是纯接口类。 +seekdb里面也用到了多重继承，这种场景是很少见的，并且要求最多只有一个基类中包含实现，其他基类都是纯接口类。 ## 4.10 操作符重载 除了容器类，自定义数据类型（`ObString`、`ObNumber` 等）以及 `ObRowkey`、`ObObj`、`ObRange` 等少量全局基础类以外，不要重载操作符（简单的结构的赋值操作除外）。如果必须违反，请事先讨论通过，并详细注释原因。 @@ -843,7 +843,7 @@ C++ STL模板类大量重载操作符，例如，比较函数，四则运算符 ## 5.1 单入口单出口 强制要求所有函数在末尾返回，禁止中途调用return、goto、exit等全局跳转指令。如果必须违反，请事先讨论，并详细注释原因。 -SeekDB认为大规模项目开发应该优先避免常见陷阱，牺牲编程复杂度是值得的。而单入口单出口能够使得开发人员不容易忘记释放资源或者恢复函数输入参数。无论任何时候，都要求函数只有一个出口。 +seekdb认为大规模项目开发应该优先避免常见陷阱，牺牲编程复杂度是值得的。而单入口单出口能够使得开发人员不容易忘记释放资源或者恢复函数输入参数。无论任何时候，都要求函数只有一个出口。 ## 5.2 函数返回值 除了如下几种例外，函数都必须返回ret错误码： @@ -968,7 +968,7 @@ if (OB_SUCCESS == ret) { // 开始一段新的逻辑 } ``` -实际编码过程中，什么时候应该采用精简写法呢？SeekDB认为，当顺序语句的每一步都只有一行语句，并且这些步骤逻辑上耦合比较紧，都应该尽量采用精简写法。然而，如果逻辑上属于多个部分，每个部分做不同的事情，那么，只应该在每个部分内部采用精简写法，而不是为了精简而精简。 +实际编码过程中，什么时候应该采用精简写法呢？seekdb认为，当顺序语句的每一步都只有一行语句，并且这些步骤逻辑上耦合比较紧，都应该尽量采用精简写法。然而，如果逻辑上属于多个部分，每个部分做不同的事情，那么，只应该在每个部分内部采用精简写法，而不是为了精简而精简。 需要注意的是，如果顺序语句后面紧接着条件语句。假如顺序语句采用精简写法变成条件语句，那么，不能将它们合并为一个大的条件语句，而应该将它们在代码结构上分开来。例如： @@ -1020,7 +1020,7 @@ if (OB_SUCCESS == ret) { ## 5.4 循环语句 在循环条件中判断 `OB_SUCCESS == ret`，防止错误码被覆盖等问题。 -SeekDB发现了大量错误码被覆盖的问题，这些问题往往都会导致严重后果，例如数据不一致，而且非常难以发现。例如： +seekdb发现了大量错误码被覆盖的问题，这些问题往往都会导致严重后果，例如数据不一致，而且非常难以发现。例如： ```cpp // 错误码被覆盖 @@ -1051,7 +1051,7 @@ while (OB_SUCCESS == ret && other_cond) { } ``` -循环语句中可能会用到break或者continue来改变执行路径。SeekDB认为应该尽量少用，这和函数单入口单出口的道理是一样的，相当于循环语句的后续代码的输入来源为多个入口，增加了代码的复杂度。如果确实有必要使用break和continue，要求通过注释详细说明原因，写代码或者Review代码时都需要格外关注。另外，考虑到后续代码的输入来源为多个入口，需要确保能说清楚后续代码的输入到底满足什么条件。 +循环语句中可能会用到break或者continue来改变执行路径。seekdb认为应该尽量少用，这和函数单入口单出口的道理是一样的，相当于循环语句的后续代码的输入来源为多个入口，增加了代码的复杂度。如果确实有必要使用break和continue，要求通过注释详细说明原因，写代码或者Review代码时都需要格外关注。另外，考虑到后续代码的输入来源为多个入口，需要确保能说清楚后续代码的输入到底满足什么条件。 ## 5.5 条件语句 条件语句需要遵守MECE原则。 @@ -1126,7 +1126,7 @@ if (cond1 && cond2) { } ``` -第一种写法分为两层，第二种写法分为一层，SeekDB只允许第一种写法。当然，这里的cond1和cond2是从业务逻辑的角度说的，指的是两段独立的业务逻辑，而不是说cond1和cond2里面不能包含&&或者||运算符。例如： +第一种写法分为两层，第二种写法分为一层，seekdb只允许第一种写法。当然，这里的cond1和cond2是从业务逻辑的角度说的，指的是两段独立的业务逻辑，而不是说cond1和cond2里面不能包含&&或者||运算符。例如： ```cpp // app_name是否为空，包含|| @@ -1147,7 +1147,7 @@ if (NULL != table_name || NULL != column_name) { 将参数声明为const可以避免一些不必要的错误，例如不变的参数因为代码错误被改变了。对于简单数据类型值传递，很多人对是否声明为const存在争议，因为这种情况声明const没有任何效果。 -考虑到SeekDB已有代码大多都已经声明为const，而且这样操作起来要更加容易，因此，只要函数参数不会发生变化，统一声明为const。 +考虑到seekdb已有代码大多都已经声明为const，而且这样操作起来要更加容易，因此，只要函数参数不会发生变化，统一声明为const。 ## 5.7 函数参数 函数参数不得超过7个，建议的顺序为：输入参数在前，输出参数在后，如果某些参数既是输入参数又是输出参数，当成输入参数处理，和其他输入参数一样放在前面，添加新的参数也需要遵守这个原则。编码的原则：代码上不相信任何人！每个函数（无论public还是private，内联函数除外）必须检查每个输入参数的合法性，强烈建议内联函数也进行这些检查（除非有严重性能问题）。所有函数（无论public还是private）都必须检查从类成员变量或者通过函数调用获得的值（例如get返回值或输出参数）的合法性，即使返回值为成功，也仍然要检查输出参数的合法性。变量（参数）检查，一个函数内只需要检查一次（如果多次调用一个或几个函数获得的值，那么每次都要检查）。这些检查包括但不限于： @@ -1209,14 +1209,14 @@ int ret = do_something(param1, NUM_TIMES, null_callback); ## 5.9 指针还是引用 函数参数可以选择指针，也可以选择引用。在遵守惯用法的前提下，更多地使用引用。 -指针参数和引用参数往往可以达到同样的效果。考虑到SeekDB编码规范中对错误判断要求比较严格，因此，更多地使用引用，减少一些冗余的错误判断代码。当然，前提是必须遵守惯用法，例如： +指针参数和引用参数往往可以达到同样的效果。考虑到seekdb编码规范中对错误判断要求比较严格，因此，更多地使用引用，减少一些冗余的错误判断代码。当然，前提是必须遵守惯用法，例如： 1. 申请对象的方法返回往往一个指针，相应的释放方法传入的也是指针。 2. 如果对象的成员是一个指针，相应的set_xxx传入的也是指针。 ## 5.10 函数长度 强制要求单个函数不超过120行。如果必须违反，请事先征得小组负责人的同意，并详细注释原因。 -大多数开源项目都会限制单个函数的行数，一般来讲，80行以上的函数往往都是不合适的。考虑到SeekDB有大量冗余的错误判断代码，限制单个函数不超过120行。如果函数过长，考虑将其分割为更加短小、易于管理的若干个函数，或者重新审视设计，修改类的结构。 +大多数开源项目都会限制单个函数的行数，一般来讲，80行以上的函数往往都是不合适的。考虑到seekdb有大量冗余的错误判断代码，限制单个函数不超过120行。如果函数过长，考虑将其分割为更加短小、易于管理的若干个函数，或者重新审视设计，修改类的结构。 ## 5.11 总结 1. 严格遵守函数单入口单出口。如果必须违反，请事先征得项目负责人和项目架构师的同意，并详细注释原因。 @@ -1232,21 +1232,21 @@ int ret = do_something(param1, NUM_TIMES, null_callback); 11. 强制要求单个函数不超过120行。如果必须违反，请事先征得小组负责人的同意，并详细注释原因。 # 6 C&C++特性 -C++的优点是灵活，缺点也正是灵活。对于C++的很多功能，SeekDB持保守态度，本节对其中一些特性进行说明。选择这些特性的原则有二： +C++的优点是灵活，缺点也正是灵活。对于C++的很多功能，seekdb持保守态度，本节对其中一些特性进行说明。选择这些特性的原则有二： 1. 谨慎原则：该特性比较“安全”，即使对于初学者，也没有特多的“坑” 2. 必要性：对OB的编码质量提升有“足够”的好处 ## 6.1 智能指针与资源Guard 不允许使用智能指针，允许通过Guard类自动释放资源。 -boost库支持智能指针，包括 `scoped_ptr`、`shared_ptr` 以及 `auto_ptr`。很多人认为智能指针能够被安全使用，尤其是 `scoped_ptr`，不过SeekDB已有代码大多都手动释放资源，且智能指针用得不好容易有副作用，因此，不允许使用智能指针。 +boost库支持智能指针，包括 `scoped_ptr`、`shared_ptr` 以及 `auto_ptr`。很多人认为智能指针能够被安全使用，尤其是 `scoped_ptr`，不过seekdb已有代码大多都手动释放资源，且智能指针用得不好容易有副作用，因此，不允许使用智能指针。 允许用户手写一些Guard类，这些类的方法会申请一些资源，这些资源会在类析构的时候自动释放掉，例如 `LockGuard`，`SessionGuard`。 ## 6.2 内存申请与释放 要求使用内存分配器申请内存，内存释放后要立即将指针置为NULL。 -SeekDB可用于内存分配的方法包括ob_malloc以及各种内存分配器，要求使用内存分配器申请内存，且申请时指定所属的模块。这样的好处是方便系统管理内存，如果出现内存泄露，很容易看出是哪个模块。另外，需要防止引用已经释放的内存空间，要求在free之后立刻将指针置为NULL。 +seekdb可用于内存分配的方法包括ob_malloc以及各种内存分配器，要求使用内存分配器申请内存，且申请时指定所属的模块。这样的好处是方便系统管理内存，如果出现内存泄露，很容易看出是哪个模块。另外，需要防止引用已经释放的内存空间，要求在free之后立刻将指针置为NULL。 ```cpp void *ptr = ob_malloc(100, ObModIds::OB_COMMON_ARRAY); @@ -1263,7 +1263,7 @@ if (NULL != ptr) { ## 6.3 字符串 禁止使用 `std::string` 类，采用 `ObString` 代替。另外，操作C字符串时，要求使用限长字符串函数。 -C++的 `std::string` 类使用非常方便，问题在于根本无法搞清楚其内部行为，例如拷贝，隐式转换。SeekDB要求尽量使用 `ObString`，其中用到的内存需要开发者手动管理。 +C++的 `std::string` 类使用非常方便，问题在于根本无法搞清楚其内部行为，例如拷贝，隐式转换。seekdb要求尽量使用 `ObString`，其中用到的内存需要开发者手动管理。 有时会使用C字符串，要注意不要使用不限制长度的字符串操作函数，包括：`strcpy/strcat/strdup/sprintf/strncpy`，而是改用对应的限长字符串操作函数：`strncat/strndup/snprintf/memcpy`。可以使用 `strlen`，用于获取字符串的长度。之所以不用 `strncpy`，那么因为如果传入buffer不够时不会自动'\0'，且存在性能问题，需要替换为 `memcpy/snprintf`。 ## 6.4 数组/字符串/缓冲区访问 @@ -1366,7 +1366,7 @@ int64_t nsize = sizeof(p); // sizeof(p)表示指针大小，在 64位机上等 ## 6.14 Boost与STL STL中只允许使用头文件定义的算法类函数，如std_sort，禁止使用其它STL或boost功能。如果必须违反，请事先征得项目负责人和项目架构师的同意，并详细注释原因。 -SeekDB对boost和STL这样的库持保守态度，我们认为正确地编写代码的重要性远远高于方便地编写代码。除了STL 定义的算法类函数，其它功能都不应该使用。 +seekdb对boost和STL这样的库持保守态度，我们认为正确地编写代码的重要性远远高于方便地编写代码。除了STL 定义的算法类函数，其它功能都不应该使用。 ## 6.15 auto **是什么** @@ -2603,7 +2603,7 @@ PAUSE的作用可以看这个回答:http://stackoverflow.com/questions/12894078/ | ERROR | DBA | 任何未预期的、不可恢复的、需要人工干预的错误 | | WARN | DBA | 可预期的并且可以由程序解决的异常情况 | | INFO（启动默认级别） | DBA | 少量对系统状态变化的标记信息。例如，添加了某用户、某表、系统进入每日合并、partition迁移等。| -| EDIAG | 研发 | Error Diagnosis，协助排查问题的诊断信息，意外的逻辑错误，比如函数参数不符合预期等，通常是SeekDB程序的BUG| +| EDIAG | 研发 | Error Diagnosis，协助排查问题的诊断信息，意外的逻辑错误，比如函数参数不符合预期等，通常是seekdb程序的BUG| | WDIAG | 研发 | Warning Diagnosis, 协助排除故障的诊断信息、预期错误，例如函数返回失败 | | TRACE | 研发 | 请求粒度的调试信息，例如执行一条SQL语句的不同阶段分别打印一条TRACE日志 | | DEBUG | 研发 | 一般性的、详细的调试信息，用以跟踪系统内部的状态、数据结构等。| diff --git a/docs/developer-guide/zh/container.md b/docs/developer-guide/zh/container.md index ec5b28f53..a3b010474 100644 --- a/docs/developer-guide/zh/container.md +++ b/docs/developer-guide/zh/container.md @@ -4,16 +4,16 @@ title: 基础数据结构 # 介绍 -C++ STL提供了很多很方便的容器，比如vector、map、unordered_map等，由于OceanBase SeekDB 编程风格与内存控制等原因，在SeekDB中禁止使用STL的容器。SeekDB 提供了一些容器实现，包括数组、链表、HashMap等，本篇文档会对这些容器做一些介绍。 +C++ STL提供了很多很方便的容器，比如vector、map、unordered_map等，由于OceanBase seekdb 编程风格与内存控制等原因，在seekdb中禁止使用STL的容器。seekdb 提供了一些容器实现，包括数组、链表、HashMap等，本篇文档会对这些容器做一些介绍。 > 本篇文档假设你对C++ STL 容器已经有了一定的理解。 > pair不属于容器，因此可以使用。 -> 由于历史遗留原因，SeekDB中包含了一些不再建议使用但是没有删除的容器代码。 +> 由于历史遗留原因，seekdb中包含了一些不再建议使用但是没有删除的容器代码。 # 字符串 -SeekDB 提供的字符串类是 ObString。代码参考 ob_string.h。 +seekdb 提供的字符串类是 ObString。代码参考 ob_string.h。 在介绍ObString的接口之前，先介绍一下ObSring的内存管理方式，这样会更加容易理解ObString的接口设计。 @@ -90,7 +90,7 @@ ObString 还有一些其它的接口，需要时浏览下 ob_string.h 代码即 # 数组 -SeekDB的数组接口设计与STL vector类似，只是更加符合SeekDB的风格。比如接口会有一个int返回值表示执行成功或失败。SeekDB 提供了多个不同实现的数组，不过它们提供的接口是类似的。 +seekdb的数组接口设计与STL vector类似，只是更加符合seekdb的风格。比如接口会有一个int返回值表示执行成功或失败。seekdb 提供了多个不同实现的数组，不过它们提供的接口是类似的。 常用的数组实现类都继承了同一个接口 `ObIArray`。我们先看一下接口定义，然后再分别介绍不同的数组实现之间的差别。 @@ -172,7 +172,7 @@ int assign(const ObIArray &other); ``` ## ObArray -ObArray 自己管理内存，在声明ObArray模板类时，需要指定分配器，或者使用默认分配器 `ModulePageAllocator`。由于SeekDB要求所有的动作都要判断返回值，因此ObArray的 `operator=` 等不带返回值的函数，不建议使用。 +ObArray 自己管理内存，在声明ObArray模板类时，需要指定分配器，或者使用默认分配器 `ModulePageAllocator`。由于seekdb要求所有的动作都要判断返回值，因此ObArray的 `operator=` 等不带返回值的函数，不建议使用。 ObArray的很多行为表现与STL vector类似，每次内存扩展时表现也类似，会扩展两倍当前数据大小，但最多 `block_size_` 大小。一个 `block_size_` 默认值是 `OB_MALLOC_NORMAL_BLOCK_SIZE` （可以认为是8K）。 @@ -338,7 +338,7 @@ DLinkNode *remove(DLinkNode *e); void clear(); ``` -SeekDB 提供了辅助 `DLinkNode` 实现 `ObDLinkNode` 和 `ObDLinkDerived`，只需要使用任一复制类即可轻松地使用 ObDList。 +seekdb 提供了辅助 `DLinkNode` 实现 `ObDLinkNode` 和 `ObDLinkDerived`，只需要使用任一复制类即可轻松地使用 ObDList。 在介绍这两个辅助类之前，先简单看一下一个基础的辅助接口实现 `ObDLinkBase`，它是上面两个辅助类的基类。它包含了 ObDList 需要的前后节点指针与一些基本的节点操作，两个辅助类都是通过继承基类来实现，而且只是使用方法不同而已。 @@ -386,9 +386,9 @@ ObDLinkDerived *nodep = alist.get_first(); # Map Map 是一个常用的数据结构，它的插入和查询的效率都非常高。通常情况下，Map有两种实现方法，一种是平衡查找树，典型的是红黑树，常见的编译器使用这种方式实现，一种是散列表，STL中是unordered_map。 -SeekDB中实现了非常多的Map，其中包括平衡查找树实现 ObRbTree 和适用于不同场景的hash map，比如 ObHashMap、ObLinkHashMap和ObLinearHashMap。 +seekdb中实现了非常多的Map，其中包括平衡查找树实现 ObRbTree 和适用于不同场景的hash map，比如 ObHashMap、ObLinkHashMap和ObLinearHashMap。 -> SeekDB 实现了很多种hash map，但是推荐使用这里介绍的几个，除非你对其它实现理解特别清晰。 +> seekdb 实现了很多种hash map，但是推荐使用这里介绍的几个，除非你对其它实现理解特别清晰。 ## ObHashMap ObHashMap 的实现在 ob_hashmap.h 中，为了方便理解 ObHashMap 的实现，我会对照STL::unordered_map来介绍。 @@ -407,7 +407,7 @@ template< 模板参数中 Key 是我们的键值，T 就是我们值的类型，Hash 是根据键值计算hash值的类或函数，KeyEqual 是判断两个键值是否相等的方法，Allocator 是一个分配器，分配的对象是键和值组成在一起的pair。 -SeekDB 中的声明是类似的： +seekdb 中的声明是类似的： ```cpp template int remove_if(Function &fn); ``` ## ObRbTree -ObRbTree 是一个红黑树实现，支持插入、删除、查找等基本操作，非线程安全。由于ObRbTree 在SeekDB中并没有使用，因此不再介绍，有兴趣的请阅读源码 `ob_rbtree.h`。 +ObRbTree 是一个红黑树实现，支持插入、删除、查找等基本操作，非线程安全。由于ObRbTree 在seekdb中并没有使用，因此不再介绍，有兴趣的请阅读源码 `ob_rbtree.h`。 # 其它 -SeekDB 还有很多基础容器的实现，比如一些队列（ObFixedQueue、ObLightyQueue、ObLinkQueue）、bitmap(ObBitmap)、tuple(ObTuple)等。如果常见的容器不能满足你的需求，可以在 `deps/oblib/src/lib` 目录下找到更多。 +seekdb 还有很多基础容器的实现，比如一些队列（ObFixedQueue、ObLightyQueue、ObLinkQueue）、bitmap(ObBitmap)、tuple(ObTuple)等。如果常见的容器不能满足你的需求，可以在 `deps/oblib/src/lib` 目录下找到更多。 diff --git a/docs/developer-guide/zh/contributing.md b/docs/developer-guide/zh/contributing.md index 2d78091f7..2491161e1 100644 --- a/docs/developer-guide/zh/contributing.md +++ b/docs/developer-guide/zh/contributing.md @@ -1,15 +1,15 @@ # 贡献指南 -OceanBase SeekDB 社区热情欢迎每一位对数据库技术热爱的开发者，期待携手开启思维碰撞之旅。无论是文档格式调整或文字修正、问题修复还是增加新功能，都是对 OceanBase SeekDB 社区参与和贡献方式之一，立刻开启您的 First Contribution 吧！ +OceanBase seekdb 社区热情欢迎每一位对数据库技术热爱的开发者，期待携手开启思维碰撞之旅。无论是文档格式调整或文字修正、问题修复还是增加新功能，都是对 OceanBase seekdb 社区参与和贡献方式之一，立刻开启您的 First Contribution 吧！ ## 概述 -本文档介绍如何为 OceanBase SeekDB 项目做出贡献，包括如何找到合适的 Issue、如何提交代码、如何创建 Pull Request 等。 +本文档介绍如何为 OceanBase seekdb 项目做出贡献，包括如何找到合适的 Issue、如何提交代码、如何创建 Pull Request 等。 ## 相关文档 - [编译与运行](build-and-run.md) - 编译项目 -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程风格 +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程风格 - [C++ 编程规范](coding-standard.md) - 详细的编程规范 - [编写单元测试](unittest.md) - 编写测试代码 @@ -109,7 +109,7 @@ git push -u origin $new_branch_name ### 10. 祝贺成为贡献者 -当 pull request 合并后，则所有的 contributing 工作全部完成，恭喜您，您成为 OceanBase SeekDB 贡献者！ +当 pull request 合并后，则所有的 contributing 工作全部完成，恭喜您，您成为 OceanBase seekdb 贡献者！ ## 贡献类型 @@ -120,4 +120,4 @@ git push -u origin $new_branch_name - **代码审查**：帮助审查其他人的 Pull Request - **社区支持**：在 Issue 和讨论区帮助其他开发者 -感谢您对 OceanBase SeekDB 项目的贡献！ +感谢您对 OceanBase seekdb 项目的贡献！ diff --git a/docs/developer-guide/zh/debug.md b/docs/developer-guide/zh/debug.md index 26b081764..0e237d466 100644 --- a/docs/developer-guide/zh/debug.md +++ b/docs/developer-guide/zh/debug.md @@ -4,34 +4,34 @@ title: 调试 # 调试方法 -本文档介绍调试 OceanBase SeekDB 的常用方法，包括 GDB 调试、日志调试、SQL 调试等。 +本文档介绍调试 OceanBase seekdb 的常用方法，包括 GDB 调试、日志调试、SQL 调试等。 ## 概述 -SeekDB 是一个复杂的分布式数据库系统，调试时需要根据不同的场景选择合适的方法。常用的调试方法包括： +seekdb 是一个复杂的分布式数据库系统，调试时需要根据不同的场景选择合适的方法。常用的调试方法包括： - **GDB 调试**：适合单进程、单线程的调试场景 - **日志调试**：最常用的调试方法，适用于大多数场景 - **SQL 调试**：使用 SQL 命令获取执行信息 - **Debug Sync**：特殊的调试同步机制 -> **提示**：建议编译 SeekDB 时使用 debug 模式，这样更容易调试。 +> **提示**：建议编译 seekdb 时使用 debug 模式，这样更容易调试。 ## 相关文档 - [编译与运行](build-and-run.md) - 编译 debug 版本 - [日志系统](logging.md) - 了解日志的详细用法 -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程风格 +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程风格 ## GDB 调试 -GDB 是一个强大的调试工具，但是使用 GDB 调试 SeekDB 是比较困难的，而且场景比较有限。 +GDB 是一个强大的调试工具，但是使用 GDB 调试 seekdb 是比较困难的，而且场景比较有限。 > **适用场景**：如果要调试单进程并且只有某一个线程，可以使用 GDB，否则建议使用日志调试。 假设已经部署了源码编译的 oceanbase。 -调试 SeekDB 与调试其他 C++ 程序类似，你可以使用 gdb，如下： +调试 seekdb 与调试其他 C++ 程序类似，你可以使用 gdb，如下： 1. 找到进程 id ```bash @@ -50,11 +50,11 @@ gdb observer 接着就可以设置断点，打印变量等。更多信息请参考 [gdb 手册](https://sourceware.org/gdb/current/onlinedocs/gdb.html/)。 -## 使用 debug-info 包调试 SeekDB +## 使用 debug-info 包调试 seekdb -要调试RPM部署的SeekDB，或者查看 coredump 文件，需要先安装或者加载 debug-info 包。推荐使用加载的模式，因为系统中会有很多 debug-info 包，而且很难清理。 +要调试RPM部署的seekdb，或者查看 coredump 文件，需要先安装或者加载 debug-info 包。推荐使用加载的模式，因为系统中会有很多 debug-info 包，而且很难清理。 -首先，从网上下载 debug-info 包，然后加载到gdb。之后，你就可以很容易地调试 SeekDB 了。 +首先，从网上下载 debug-info 包，然后加载到gdb。之后，你就可以很容易地调试 seekdb 了。 下面是一些提示。 @@ -65,7 +65,7 @@ gdb observer # in the observer runtime path clusters/local/bin [83] $ ./observer -V ./observer -V -observer (OceanBase SeekDB 1.0.0.0) +observer (OceanBase seekdb 1.0.0.0) REVISION: 102000042023061314-43bca414d5065272a730c92a645c3e25768c1d05 BUILD_BRANCH: HEAD @@ -86,7 +86,7 @@ Copyright (c) 2011-2022 OceanBase Inc. ```bash clusters/local/bin [83] $ LD_LIBRARY_PATH=../lib:$LD_LIBRARY_PATH ./observer -V ./observer -V -observer (OceanBase SeekDB 1.0.0.0) +observer (OceanBase seekdb 1.0.0.0) REVISION: 102000042023061314-43bca414d5065272a730c92a645c3e25768c1d05 BUILD_BRANCH: HEAD @@ -143,7 +143,7 @@ rpm2cpio seekdb-debuginfo-1.0.0.0-102000042023061314.el7.x86_64.rpm | cpio -div `observer.debug` 是我们要的 debug-info 包，`f87ee72d228069aab083d8e6d2fa2fcb5c03f2.debug` 是一个软链接。 -**使用 debug-info 包调试 SeekDB** +**使用 debug-info 包调试 seekdb** 使用gdb命令 attch 到一个进程或者打开coredump文件。 @@ -210,9 +210,9 @@ Reading symbols from usr/lib/debug/home/admin/oceanbase/bin/observer.debug... ## 日志调试 -日志是调试 SeekDB 最常用的方法，易于使用，适用于大多数场景。 +日志是调试 seekdb 最常用的方法，易于使用，适用于大多数场景。 -在常见的场景中，可以在代码中添加日志并打印变量，然后重新编译和部署 SeekDB。 +在常见的场景中，可以在代码中添加日志并打印变量，然后重新编译和部署 seekdb。 > **提示**：关于日志的详细用法，请参考 [日志系统](logging.md) 文档。 @@ -229,7 +229,7 @@ LOG_DEBUG("insert sql generated", K(insert_sql)); ## 如何搜索日志 -日志文件在 SeekDB 运行目录的 `log` 目录下。你可以使用 `grep` 命令搜索日志。 +日志文件在 seekdb 运行目录的 `log` 目录下。你可以使用 `grep` 命令搜索日志。 一个日志的例子。 ``` @@ -345,7 +345,7 @@ obclient> show trace; ## Debug Sync -在使用 GDB 调试 SeekDB 的时候，可能会出现问题，因为 GDB 会挂起进程，而 SeekDB 依赖心跳来正常工作。所以我们提供了一个 debug sync 机制来解决这个问题。 +在使用 GDB 调试 seekdb 的时候，可能会出现问题，因为 GDB 会挂起进程，而 seekdb 依赖心跳来正常工作。所以我们提供了一个 debug sync 机制来解决这个问题。 > **注意**：Debug Sync 在 release 模式下也可以用，所以它在生产环境中是开启的。 diff --git a/docs/developer-guide/zh/ide-settings.md b/docs/developer-guide/zh/ide-settings.md index 35a25a9b5..1815477f2 100644 --- a/docs/developer-guide/zh/ide-settings.md +++ b/docs/developer-guide/zh/ide-settings.md @@ -5,11 +5,11 @@ title: IDE 配置 # IDE 配置 -本文档介绍如何配置开发环境以便更好地阅读 OceanBase SeekDB 的代码。 +本文档介绍如何配置开发环境以便更好地阅读 OceanBase seekdb 的代码。 ## 概述 -为了更好的阅读 OceanBase SeekDB 的代码，我们建议使用一个可以方便索引 SeekDB 代码的 IDE。 +为了更好的阅读 OceanBase seekdb 的代码，我们建议使用一个可以方便索引 seekdb 代码的 IDE。 - **Windows**：推荐使用 `Source Insight` - **Mac/Linux**：推荐使用 `VSCode + ccls` @@ -19,7 +19,7 @@ title: IDE 配置 ## 相关文档 - [编译与运行](build-and-run.md) - 编译项目 -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程风格 +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程风格 ## 为什么选择 VSCode + ccls @@ -32,11 +32,11 @@ title: IDE 配置 在 C/C++ LSP 领域，比较有名的工具有 clangd 和 ccls。这里我们推荐 ccls，因为： 1. **索引性能**：ccls 构建索引的速度比 clangd 慢，但是构建完成后，ccls 访问索引的速度比 clangd 快 -2. **Unity 编译支持**：clangd 不支持 unity 编译，而 SeekDB 是通过 unity 编译的，clangd 无法通过 compile_commands.json 构建索引 +2. **Unity 编译支持**：clangd 不支持 unity 编译，而 seekdb 是通过 unity 编译的，clangd 无法通过 compile_commands.json 构建索引 ### 远程开发 -SeekDB 的代码量非常大，而且 SeekDB 不能在 Mac 或者 Windows 下编译，所以我们建议在远程服务器上下载代码，然后在本地使用 VSCode 访问远程服务器上的代码。 +seekdb 的代码量非常大，而且 seekdb 不能在 Mac 或者 Windows 下编译，所以我们建议在远程服务器上下载代码，然后在本地使用 VSCode 访问远程服务器上的代码。 ## 在远程服务器上配置 ccls @@ -127,7 +127,7 @@ ccls --version ## C/C++ 插件 -不推荐使用C/C++插件，因为无法为SeekDB提供良好的索引功能，并且与ccls插件不兼容。 +不推荐使用C/C++插件，因为无法为seekdb提供良好的索引功能，并且与ccls插件不兼容。 如果有一些简单的场景，可以在VSCode的扩展商店中下载并安装C/C++插件。 @@ -151,7 +151,7 @@ C/C++插件可以自动完成代码和语法高亮，但是这个插件无法为 2. 设置 `ccls.index.threads`。ccls 默认使用系统80%的CPU核心作为默认的并行度。我们可以在VSCode的配置页面中搜索 `threads` 并设置如下数字。 -> 默认情况下，SeekDB使用unity编译，比普通情况下消耗更多的内存。如果并行度太高，例如8核16G的系统，系统可能会挂起。 +> 默认情况下，seekdb使用unity编译，比普通情况下消耗更多的内存。如果并行度太高，例如8核16G的系统，系统可能会挂起。 ![ccls threads config](images/ide-settings-ccls-threads-config.png) @@ -174,7 +174,7 @@ cd seekdb bash build.sh ccls --init ``` -执行完成后，可以在 SeekDB 源码根目录下看到 `compile_commands.json` 文件。 +执行完成后，可以在 seekdb 源码根目录下看到 `compile_commands.json` 文件。 ### 步骤 3: 重启 VSCode 并构建索引 diff --git a/docs/developer-guide/zh/logging.md b/docs/developer-guide/zh/logging.md index 4ccbaf5c2..8c48db4a9 100644 --- a/docs/developer-guide/zh/logging.md +++ b/docs/developer-guide/zh/logging.md @@ -1,19 +1,19 @@ --- -title: OceanBase SeekDB 系统日志介绍 +title: OceanBase seekdb 系统日志介绍 --- -# OceanBase SeekDB 系统日志介绍 +# OceanBase seekdb 系统日志介绍 ## 介绍 -本篇文档主要介绍 OceanBase SeekDB 的系统日志，包括日志的分类、级别，如何在程序中输出日志，以及一些日志的实现细节。 +本篇文档主要介绍 OceanBase seekdb 的系统日志，包括日志的分类、级别，如何在程序中输出日志，以及一些日志的实现细节。 ## 系统日志介绍 -与常见的应用系统类似，系统日志是SeekDB开发人员排查问题时常用的重要手段之一。 +与常见的应用系统类似，系统日志是seekdb开发人员排查问题时常用的重要手段之一。 -SeekDB 的系统日志存储在observero工作目录下的log目录下面。 +seekdb 的系统日志存储在observero工作目录下的log目录下面。 | 日志文件名称 | 记录的信息 | | ------------------ | ----------------------------- | @@ -38,7 +38,7 @@ SeekDB 的系统日志存储在observero工作目录下的log目录下面。 ## 日志回收 -SeekDB的日志可以配置文件个数上限，以防止日志文件占用过大的磁盘空间。 +seekdb的日志可以配置文件个数上限，以防止日志文件占用过大的磁盘空间。 如果 `enable_syslog_recycle = true` 且 `max_syslog_file_count > 0` ，每种日志文件的数量不能超过 `max_syslog_file_count`。日志内容刷新到磁盘中时触发旧日志文件回收。 @@ -48,12 +48,12 @@ SeekDB的日志可以配置文件个数上限，以防止日志文件占用过 新日志文件都会在开头打印一个特殊日志，信息包含当前节点的IP和端口、版本号、以及一些系统信息，参考 `ObLogger::log_new_file_info`。 ``` -[2023-12-26 13:15:58.612579] INFO New syslog file info: [address: "127.0.0.1:2882", observer version: OceanBase SeekDB 1.0.0.0, revision: 101010012023111012-2f6924cd5a576f09d6e7f212fac83f1a15ff531a, sysname: Linux, os release: 3.10.0-327.ali2019.alios7.x86_64, machine: x86_64, tz GMT offset: 08:00] +[2023-12-26 13:15:58.612579] INFO New syslog file info: [address: "127.0.0.1:2882", observer version: OceanBase seekdb 1.0.0.0, revision: 101010012023111012-2f6924cd5a576f09d6e7f212fac83f1a15ff531a, sysname: Linux, os release: 3.10.0-327.ali2019.alios7.x86_64, machine: x86_64, tz GMT offset: 08:00] ``` ## 日志级别 -与常见的系统打日志方法类似，SeekDB 也提供了日志宏来打印不同级别的日志： +与常见的系统打日志方法类似，seekdb 也提供了日志宏来打印不同级别的日志： | 级别 | 代码宏 | 说明 | | ----- | --------- | ---- | @@ -63,7 +63,7 @@ SeekDB的日志可以配置文件个数上限，以防止日志文件占用过 | WARN | LOG_DBA_WARN | 面向DBA的日志。出现非预期场景，observer能提供服务，但行为可能不符合预期，比如我们的写入限流 | | ERROR | LOG_DBA_ERROR | 面向DBA的日志。observer不能提供正常服务的异常，如磁盘满监听端口被占用等。也可以是我们产品化后的一些内部检查报错，如我们的4377(dml defensive check error), 4103 (data checksum error)等，需DBA干预恢复 | | WDIAG | LOG_WARN | Warning Diagnosis, 协助故障排查的诊断信息，预期内的错误，如函数返回失败。级别与WARN相同 | -| EDIAG | LOG_ERROR | Error Diagnosis, 协助故障排查的诊断信息，非预期的逻辑错误，如函数参数不符合预期等，通常为SeekDB程序BUG。级别与ERROR相同 | +| EDIAG | LOG_ERROR | Error Diagnosis, 协助故障排查的诊断信息，非预期的逻辑错误，如函数参数不符合预期等，通常为seekdb程序BUG。级别与ERROR相同 | > 这里仅介绍了最常用的日志级别，更详细的信息参考 `ob_parameter_seed.ipp` 中关于 `syslog_level` 的配置，以及`ob_log_module.h` 文件中 `LOG_ERROR` 等宏定义。 @@ -72,7 +72,7 @@ SeekDB的日志可以配置文件个数上限，以防止日志文件占用过 有三种方式调整日志级别： -- SeekDB 程序在启动时会读取配置文件或通过命令行参数输入系统日志级别配置，配置项名称是`syslog_level`。 +- seekdb 程序在启动时会读取配置文件或通过命令行参数输入系统日志级别配置，配置项名称是`syslog_level`。 - 启动后也可以通过MySQL客户端连接，执行SQL命令 `alter system set syslog_level='DEBUG`; - 通过SQL HINT修改执行请求时的日志级别，比如 `select /*+ log_level("ERROR") */ * from foo;`。这种方式只对当前SQL请求相关的日志有效。 @@ -88,11 +88,11 @@ if (OB_FAIL(OB_LOGGER.parse_set(conf_->syslog_level, ## 如何打印日志 -常见的系统会使用C++ stream方式或C fprintf风格打印日志，但是SeekDB略有不同。接下来从示例入手看如何打印日志。 +常见的系统会使用C++ stream方式或C fprintf风格打印日志，但是seekdb略有不同。接下来从示例入手看如何打印日志。 ### 打印日志的例子 -与fprintf不一样，SeekDB的系统日志没有formt string，而只有"info"参数，和各个参数信息。比如： +与fprintf不一样，seekdb的系统日志没有formt string，而只有"info"参数，和各个参数信息。比如： ```cpp LOG_INFO("start stmt", K(ret), @@ -173,9 +173,9 @@ cflict_txs:[]}) 对于开发者来说，我们只需要关心如何输出我们的对象信息。通常我们编写`K(obj)`即可将我们想要的信息输出到日志中。下面介绍一些细节。 -SeekDB 为了避免format string的一些错误，使用自动识别类型然后序列化来解决这个问题。日志任意参数中会识别为多个Key Value对，其中Key是要打印的字段名称，Value是字段的值。比如上面的示例中的 `"consistency_level_in_plan_ctx", plan_ctx->get_consistency_level()` ，就是打印了一个字段的名称和值，SeekDB 自动识别 Value 的类型并转换为字符串。 +seekdb 为了避免format string的一些错误，使用自动识别类型然后序列化来解决这个问题。日志任意参数中会识别为多个Key Value对，其中Key是要打印的字段名称，Value是字段的值。比如上面的示例中的 `"consistency_level_in_plan_ctx", plan_ctx->get_consistency_level()` ，就是打印了一个字段的名称和值，seekdb 自动识别 Value 的类型并转换为字符串。 -因为大部分日志都是打印对象的某个字段，所以SeekDB提供了一些宏来简化打印日志的操作。最常用的就是 `K`，以上面的例子 `K(ret)`，其展开后在代码中是： +因为大部分日志都是打印对象的某个字段，所以seekdb提供了一些宏来简化打印日志的操作。最常用的就是 `K`，以上面的例子 `K(ret)`，其展开后在代码中是： ```cpp "ret", ret @@ -186,7 +186,7 @@ SeekDB 为了避免format string的一些错误，使用自动识别类型然后 ret=-5595 ``` -SeekDB 还提供了一些其它的宏，在不同的场景下使用不同的宏。 +seekdb 还提供了一些其它的宏，在不同的场景下使用不同的宏。 > 日志参数宏定义可以在 `ob_log_module.h` 文件中找到。 @@ -194,7 +194,7 @@ SeekDB 还提供了一些其它的宏，在不同的场景下使用不同的宏 | --------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | K | K(ret) | 展开后就是 `"ret", ret`。参数可以是一个简单值，也可以是一个普通对象 | | K_ | K_(consistency_level) | 展开后是 `"consistency_level", consistency_level_`。与 K 不同的是，会在展开的 Value 后自动增加 `_`后缀，用在类成员变量的打印 | -| KR | KR(ret) | 展开后是 `"ret", ret, "ret", common::ob_error_name(ret)`。这个宏是为了方便打印错误码与错误码名称。在 SeekDB 中，通常使用 `ret` 作为函数的返回值，而每个返回值会有一个对应的字符串描述。`ob_error_name` 就可以获得错误码对应的字符串描述。注意，这个宏只能用在非lib代码中 | +| KR | KR(ret) | 展开后是 `"ret", ret, "ret", common::ob_error_name(ret)`。这个宏是为了方便打印错误码与错误码名称。在 seekdb 中，通常使用 `ret` 作为函数的返回值，而每个返回值会有一个对应的字符串描述。`ob_error_name` 就可以获得错误码对应的字符串描述。注意，这个宏只能用在非lib代码中 | | KCSTRING/
KCSTRING_ | KCSTRING(consistency_level_name) | 展开后是 `"consistency_level_name", consistency_level_name`。这个宏是为了打印 C 格式的字符串。由于`const char *` 类型的变量在C++中未必表示一个字符串，比如一个二进制buffer，那么打印这个变量的值时，当做C字符串来打印输出的话，会遇到访问非法内存的错误，所以增加了这个宏，用来明确表示打印C字符串 | | KP/KP_ | KP(plan) | 展开后是 `"plan", plan`，其中 `plan` 是一个指针。这个宏将会打印出某个指针的十六进制值 | | KPC/KPC_ | KPC(session) | 输入参数是对象指针。如果是NULL时会输出NULL，否则调用指针的to_string方法输出字符串 | @@ -208,14 +208,14 @@ SeekDB 还提供了一些其它的宏，在不同的场景下使用不同的宏 ### 值如何转换为字符串 -SeekDB 会自动识别日志中想要打印的值的类型，然后将其转换为字符串。比如上面的例子中，`ret` 是一个 `int` 类型的变量，而 `plan_ctx->get_consistency_level()` 返回的是一个 `enum` 类型的变量，这两个变量都会被转换为字符串。 +seekdb 会自动识别日志中想要打印的值的类型，然后将其转换为字符串。比如上面的例子中，`ret` 是一个 `int` 类型的变量，而 `plan_ctx->get_consistency_level()` 返回的是一个 `enum` 类型的变量，这两个变量都会被转换为字符串。 -不过由于SeekDB不知道如何将一个普通对象转换为字符串，所以需要用户自己实现一个 `TO_STRING_KV` 函数，来将对象转换为字符串。比如上面的例子中，`snapshot` 是一个 `ObTxReadSnapshot` 类型的对象，这个对象实现了 `TO_STRING_KV` 函数，所以可以直接打印。 +不过由于seekdb不知道如何将一个普通对象转换为字符串，所以需要用户自己实现一个 `TO_STRING_KV` 函数，来将对象转换为字符串。比如上面的例子中，`snapshot` 是一个 `ObTxReadSnapshot` 类型的对象，这个对象实现了 `TO_STRING_KV` 函数，所以可以直接打印。 **普通值转换为字符串** -SeekDB 可以自动识别简单类型的值，比如`int`、`int64_t`、`double`、`bool`、`const char *` 等，将其转换为字符串。对于枚举类型，会当做数字来处理。对于指针，将会使用十六进制的方式输出指针值。 +seekdb 可以自动识别简单类型的值，比如`int`、`int64_t`、`double`、`bool`、`const char *` 等，将其转换为字符串。对于枚举类型，会当做数字来处理。对于指针，将会使用十六进制的方式输出指针值。 @@ -245,7 +245,7 @@ class ObTxReadSnapshot { ### 日志模块 -SeekDB 的日志是区分模块的，而且可以支持子模块。比如上面的例子中，`[SQL.EXE]` 就是一个模块，`SQL` 是一个主模块，`EXE` 是一个子模块。日志模块的定义可以参考 `ob_log_module.h` 文件中 `LOG_MOD_BEGIN` 和 `DEFINE_LOG_SUB_MOD` 相关的代码。 +seekdb 的日志是区分模块的，而且可以支持子模块。比如上面的例子中，`[SQL.EXE]` 就是一个模块，`SQL` 是一个主模块，`EXE` 是一个子模块。日志模块的定义可以参考 `ob_log_module.h` 文件中 `LOG_MOD_BEGIN` 和 `DEFINE_LOG_SUB_MOD` 相关的代码。 @@ -261,7 +261,7 @@ SeekDB 的日志是区分模块的，而且可以支持子模块。比如上面 **如何明确的指定模块名称？** -使用上面的方式确实有些不够灵活，SeekDB 还有另一种方式来指定模块名称，即使用宏 `OB_MOD_LOG` 或 `OB_SUB_MOD_LOG`。这两个宏的使用方法与 `LOG_WARN` 类似，只是多了模块参数与日志级别： +使用上面的方式确实有些不够灵活，seekdb 还有另一种方式来指定模块名称，即使用宏 `OB_MOD_LOG` 或 `OB_SUB_MOD_LOG`。这两个宏的使用方法与 `LOG_WARN` 类似，只是多了模块参数与日志级别： ```cpp OB_MOD_LOG(parMod, level, info_string, args...) @@ -269,7 +269,7 @@ OB_SUB_MOD_LOG(parMod, subMod, level, info_string, args...) ``` **设置模块的日志级别** -SeekDB 除了可以设置全局和当前线程的日志级别，还可以调整某个模块的日志级别。当前可以通过 SQL HINT 的方式修改执行请求时的某个模块的日志级别，比如： +seekdb 除了可以设置全局和当前线程的日志级别，还可以调整某个模块的日志级别。当前可以通过 SQL HINT 的方式修改执行请求时的某个模块的日志级别，比如： ```sql select /*+ log_level("SHARE.SCHEMA:ERROR") */ * from foo; @@ -279,26 +279,26 @@ select /*+ log_level("SHARE.SCHEMA:ERROR") */ * from foo; ### 日志时间 -SeekDB 的日志时间是当前本地时间的微秒数。 -由于将时间戳转换为字符串是一个相当耗时的事情，SeekDB 将时间戳转换缓存下来以加速该过程，具体可以参考 `ob_fast_localtime` 函数。 +seekdb 的日志时间是当前本地时间的微秒数。 +由于将时间戳转换为字符串是一个相当耗时的事情，seekdb 将时间戳转换缓存下来以加速该过程，具体可以参考 `ob_fast_localtime` 函数。 ### 线程标识 当前会记录两个线程相关的信息： - 线程号：系统调用 `__NR_gettid` 返回的信息（系统调用比较低效，这个值会缓存下来）； -- 线程名称：线程名称字段中可能会包含租户ID、线程池类型和线程池中的编号。SeekDB的线程号是通过 `set_thread_name` 函数设置的，还会显示在 `top` 命令中。 +- 线程名称：线程名称字段中可能会包含租户ID、线程池类型和线程池中的编号。seekdb的线程号是通过 `set_thread_name` 函数设置的，还会显示在 `top` 命令中。 > NOTE：线程名称是由创建的线程决定的，由于创建线程的租户可能与此线程后续运行的租户不同，所以线程名称中的租户可能不对。 ### 日志限速 -SeekDB 支持两种日志限速：一个普通系统日志磁盘IO带宽限制，一个是WARN系统日志限制。 +seekdb 支持两种日志限速：一个普通系统日志磁盘IO带宽限制，一个是WARN系统日志限制。 **系统日志带宽限速** -SeekDB 会按照磁盘带宽来限制日志输出。日志带宽限速不会针对不同的日志级别限速。如果日志限速，可能会打印限速日志，关键字 `REACH SYSLOG RATE LIMIT `。 +seekdb 会按照磁盘带宽来限制日志输出。日志带宽限速不会针对不同的日志级别限速。如果日志限速，可能会打印限速日志，关键字 `REACH SYSLOG RATE LIMIT `。 限速日志示例： @@ -311,7 +311,7 @@ SeekDB 会按照磁盘带宽来限制日志输出。日志带宽限速不会针 限速的代码细节请参考 `check_tl_log_limiter` 函数。 **WDIAG 日志限速** -SeekDB 对WARN级别的日志做了限流，每个错误码每秒钟默认限制输出200条日志。超过限制会输出限流日志，关键字 `Throttled WDIAG logs in last second`。可以通过配置项 `diag_syslog_per_error_limit` 来调整限流阈值。 +seekdb 对WARN级别的日志做了限流，每个错误码每秒钟默认限制输出200条日志。超过限制会输出限流日志，关键字 `Throttled WDIAG logs in last second`。可以通过配置项 `diag_syslog_per_error_limit` 来调整限流阈值。 限流日志示例： @@ -328,7 +328,7 @@ SeekDB 对WARN级别的日志做了限流，每个错误码每秒钟默认限制 ### DBA日志 -SeekDB 中还有两类特殊的日志，LOG_DBA_WARN 和 LOG_DBA_ERROR，分别对应了WARN和ERROR日志。由于SeekDB日志量特别大，并且大部分只有研发人员才能理解，为DBA运维排查问题带来了一定的负担，因此增加这两种日志，希望让DBA仅关注少量的这两类日志即可排查系统问题。而使用 LOG_WARN 和 LOG_ERROR 输出的日志被转换成 WDIAG 和 EDIAG 日志，帮助开发人员排查问题。 +seekdb 中还有两类特殊的日志，LOG_DBA_WARN 和 LOG_DBA_ERROR，分别对应了WARN和ERROR日志。由于seekdb日志量特别大，并且大部分只有研发人员才能理解，为DBA运维排查问题带来了一定的负担，因此增加这两种日志，希望让DBA仅关注少量的这两类日志即可排查系统问题。而使用 LOG_WARN 和 LOG_ERROR 输出的日志被转换成 WDIAG 和 EDIAG 日志，帮助开发人员排查问题。 ### 输出提示信息到用户终端 @@ -352,7 +352,7 @@ LOG_USER_ERROR 宏定义如下： ### 健康日志 -SeekDB 会周期性的输出一些内部状态信息，比如各模块、租户的内存信息，到日志中，方便查找问题。这种日志通常一条会输出多行数据，比如： +seekdb 会周期性的输出一些内部状态信息，比如各模块、租户的内存信息，到日志中，方便查找问题。这种日志通常一条会输出多行数据，比如： ```txt [2023-12-26 13:15:58.608131] INFO [LIB] print_usage (ob_tenant_ctx_allocator.cpp:176) [35582][MemDumpTimer][T0][Y0-0000000000000000-0-0] [lt=116] @@ -367,4 +367,4 @@ SeekDB 会周期性的输出一些内部状态信息，比如各模块、租户 这种数据会查找历史问题很有帮助。 ### ERROR 日志 -对系统出现的一般错误，比如处理某个请求时，出现了异常，会以WARN级别输出日志。只有影响到SeekDB进程正常运行，或者认为有严重问题时，会以ERROR级别输出日志。因此如果遇到进程异常退出，或者无法启动时，搜索ERROR日志会更有效地查找问题原因。 +对系统出现的一般错误，比如处理某个请求时，出现了异常，会以WARN级别输出日志。只有影响到seekdb进程正常运行，或者认为有严重问题时，会以ERROR级别输出日志。因此如果遇到进程异常退出，或者无法启动时，搜索ERROR日志会更有效地查找问题原因。 diff --git a/docs/developer-guide/zh/memory.md b/docs/developer-guide/zh/memory.md index 31b3709fd..470399ea3 100644 --- a/docs/developer-guide/zh/memory.md +++ b/docs/developer-guide/zh/memory.md @@ -3,7 +3,7 @@ title: 内存管理 --- # 简介 -内存管理是所有大型C++工程中最重要的模块之一。由于OceanBase SeekDB还需要处理多租户内存资源隔离问题，因此SeekDB相较于普通的C++工程，内存管理更加复杂。通常，一个良好的内存管理模块需要考虑以下几个问题： +内存管理是所有大型C++工程中最重要的模块之一。由于OceanBase seekdb还需要处理多租户内存资源隔离问题，因此seekdb相较于普通的C++工程，内存管理更加复杂。通常，一个良好的内存管理模块需要考虑以下几个问题： - 易用。设计的接口比较容器理解和使用，否则代码会很难阅读和维护，也会更容易出现内存错误； - 高效。高效的内存分配器对性能影响至关重大，尤其是在高并发场景下； @@ -13,14 +13,14 @@ title: 内存管理 - 透明的接口设计。如何让开发人员无感、或极少的需要关心不同租户的内存管理工作； - 高效准确。内存充足应该必须申请成功，租户内存耗尽应该及时察觉，是多租户内存管理的最基础条件。 -本篇文章将会介绍SeekDB 中常用的内存分配接口与内存管理相关的习惯用法，关于内存管理的技术细节，请参考[内存管理](https://open.oceanbase.com/blog/8501613072)(中文版）。 +本篇文章将会介绍seekdb 中常用的内存分配接口与内存管理相关的习惯用法，关于内存管理的技术细节，请参考[内存管理](https://open.oceanbase.com/blog/8501613072)(中文版）。 -# OceanBase SeekDB 内存管理常用接口与方式 -SeekDB 针对不同场景，提供了不同的内存分配器。另外为了提高程序执行效率，有一些约定的实现，比如reset/reuse等。 +# OceanBase seekdb 内存管理常用接口与方式 +seekdb 针对不同场景，提供了不同的内存分配器。另外为了提高程序执行效率，有一些约定的实现，比如reset/reuse等。 ## ob_malloc -SeekDB数据库自研了一套libc风格的接口函数ob_malloc/ob_free/ob_realloc，这套接口会根据tenant_id、ctx_id、label等属性动态申请大小为size的内存块，并且为内存块打上标记，确定归属。这不仅方便了多租户的资源管理，而且对诊断内存问题有很大帮助。 +seekdb数据库自研了一套libc风格的接口函数ob_malloc/ob_free/ob_realloc，这套接口会根据tenant_id、ctx_id、label等属性动态申请大小为size的内存块，并且为内存块打上标记，确定归属。这不仅方便了多租户的资源管理，而且对诊断内存问题有很大帮助。 ob_malloc会根据tenant_id、ctx_id索引到相应的ObTenantCtxAllocator，ObTenantCtxAllocator会按照当前租户上下文环境分配内存。 ob_free通过偏移运算求出即将释放的内存所对应的对象分配器，再将内存放回内存池。 ob_realloc与libc的realloc不同，它不是在原有地址上扩容，而是先通过ob_malloc+memcpy将数据复制到另一块内存上，再调用ob_free释放原有内存。 @@ -36,13 +36,13 @@ inline void *ob_realloc(void *ptr, const int64_t nbyte, const ObMemAttr &attr); ## ObArenaAllocator 设计特点是多次申请一次释放，只有reset或者析构才真正释放内存，在这之前申请的内存即使主动调用free也不会有任何效用。 -ObArenaAllocator 适用于很多小内存申请，短时间内存会释放的场景。比如一次SQL请求中，会频繁申请很多小内存，并且这些小内存的生命周期会持续整个请求期间。通常情况下，一次SQL的请求处理时间也非常短。这种内存分配方式对于小内存和避免内存泄露上非常有效。在SeekDB的代码中如果遇到只有申请内存却找不到释放内存的地方，不要惊讶。 +ObArenaAllocator 适用于很多小内存申请，短时间内存会释放的场景。比如一次SQL请求中，会频繁申请很多小内存，并且这些小内存的生命周期会持续整个请求期间。通常情况下，一次SQL的请求处理时间也非常短。这种内存分配方式对于小内存和避免内存泄露上非常有效。在seekdb的代码中如果遇到只有申请内存却找不到释放内存的地方，不要惊讶。 > 代码参考 `page_arena.h` ## ObMemAttr 介绍 -SeekDB 使用 `ObMemAttr` 来标记一段内存。 +seekdb 使用 `ObMemAttr` 来标记一段内存。 ```cpp struct ObMemAttr @@ -63,7 +63,7 @@ struct ObMemAttr **label** -在最开始，SeekDB 使用预定义的方式为各个模块创建内存标签。但是随着代码量的增长，预定义标签的方式不太适用，当前改用直接使用常量字符串的方式构造ObLabel。在使用ob_malloc时，也可以直接传入常量字符串当做ObLabel参数。 +在最开始，seekdb 使用预定义的方式为各个模块创建内存标签。但是随着代码量的增长，预定义标签的方式不太适用，当前改用直接使用常量字符串的方式构造ObLabel。在使用ob_malloc时，也可以直接传入常量字符串当做ObLabel参数。 **ctx_id** @@ -89,7 +89,7 @@ ctx id是预定义的，可以参考 `alloc_struct.h`。每个租户的每个ctx ## init/destroy/reset/reuse -缓存是提升程序性能的重要手段之一，对象重用也是缓存的一种方式，一方面减少内存申请释放的频率，另一方面可以减少一些构造析构的开销。SeekDB 中有大量的对象重用，并且形成了一些约定，比如reset和reuse函数。 +缓存是提升程序性能的重要手段之一，对象重用也是缓存的一种方式，一方面减少内存申请释放的频率，另一方面可以减少一些构造析构的开销。seekdb 中有大量的对象重用，并且形成了一些约定，比如reset和reuse函数。 **reset** @@ -99,7 +99,7 @@ ctx id是预定义的，可以参考 `alloc_struct.h`。每个租户的每个ctx 相较于reset，更加轻量。尽量不去释放一些开销较大的资源，比如 `PageArena::reuse`。 -SeekDB 中还有两个常见的接口是`init`和`destroy`。在构造函数中仅做一些非常轻量级的初始化工作，比如指针初始化为`nullptr`。 +seekdb 中还有两个常见的接口是`init`和`destroy`。在构造函数中仅做一些非常轻量级的初始化工作，比如指针初始化为`nullptr`。 ## SMART_VAR/HEAP_VAR SMART_VAR是定义局部变量的辅助接口，使用该接口的变量总是优先从栈上分配，当栈内存不足时退化为从堆上分配。对于那些不易优化的大型局部变量（>8K），该接口即保证了常规场景的性能，又能将栈容量安全地降下来。接口定义如下： diff --git a/docs/developer-guide/zh/mysqltest.md b/docs/developer-guide/zh/mysqltest.md index 7b60a4038..99bf06274 100644 --- a/docs/developer-guide/zh/mysqltest.md +++ b/docs/developer-guide/zh/mysqltest.md @@ -1,14 +1,14 @@ # 使用 obd.sh 运行 mysqltest -要使用 obd.sh 运行 mysqltest 测试，需要通过 obd.sh 部署 OceanBase SeekDB 数据库。本文从编译源代码开始，使用示例介绍如何使用 obd.sh 部署 SeekDB 数据库并运行 mysqltest 测试。 +要使用 obd.sh 运行 mysqltest 测试，需要通过 obd.sh 部署 OceanBase seekdb 数据库。本文从编译源代码开始，使用示例介绍如何使用 obd.sh 部署 seekdb 数据库并运行 mysqltest 测试。 ## 背景 -为了简化开发者的操作步骤，降低其理解成本，我们将一些 OBD 命令封装到 obd.sh 脚本中，并将脚本存放在 SeekDB 源代码的 oceanbase/tools/deploy 目录下。本文通过在 OBD 中调用 [obd test mysqltest](https://www.oceanbase.com/docs/community-obd-cn-10000000002048173) 命令，运行 mysqltest 测试。 +为了简化开发者的操作步骤，降低其理解成本，我们将一些 OBD 命令封装到 obd.sh 脚本中，并将脚本存放在 seekdb 源代码的 oceanbase/tools/deploy 目录下。本文通过在 OBD 中调用 [obd test mysqltest](https://www.oceanbase.com/docs/community-obd-cn-10000000002048173) 命令，运行 mysqltest 测试。 ## 相关概念 -mysqltest 是SeekDB数据库中的一种准入测试，简单来说，它以编写的 case 文件为输入，将数据库的输出与预期输出进行比较。SeekDB数据库中 mysqltest 测试的 case 都位于 `tools/deploy/mysql_test` 目录下。 +mysqltest 是seekdb数据库中的一种准入测试，简单来说，它以编写的 case 文件为输入，将数据库的输出与预期输出进行比较。seekdb数据库中 mysqltest 测试的 case 都位于 `tools/deploy/mysql_test` 目录下。 `case` 是 mysqltest 的最小执行单元，一个 `case` 至少包含一个 test 文件和一个 result 文件。对 case 进行分类形成 `suite`，`suite` 是 case 的集合。 diff --git a/docs/developer-guide/zh/toolchain.md b/docs/developer-guide/zh/toolchain.md index 6b8aa4a79..03f8a1a04 100644 --- a/docs/developer-guide/zh/toolchain.md +++ b/docs/developer-guide/zh/toolchain.md @@ -1,19 +1,19 @@ # 安装工具链 -在编译 OceanBase SeekDB 源码之前，需要先在开发环境中安装 C++ 工具链。本文档介绍如何在不同操作系统上安装所需的工具链。 +在编译 OceanBase seekdb 源码之前，需要先在开发环境中安装 C++ 工具链。本文档介绍如何在不同操作系统上安装所需的工具链。 ## 概述 -SeekDB 是一个 C++ 项目，需要特定的编译工具链。请根据你的操作系统选择对应的安装方法。 +seekdb 是一个 C++ 项目，需要特定的编译工具链。请根据你的操作系统选择对应的安装方法。 ## 相关文档 -- [编译与运行](build-and-run.md) - 编译和运行 SeekDB +- [编译与运行](build-and-run.md) - 编译和运行 seekdb - [IDE 配置](ide-settings.md) - 配置开发环境 ## 支持的操作系统 -OceanBase SeekDB 并不支持所有的操作系统，特别是 Windows 和 Mac OS X。 +OceanBase seekdb 并不支持所有的操作系统，特别是 Windows 和 Mac OS X。 这是当前兼容的操作系统列表： @@ -86,5 +86,5 @@ make --version 工具链安装完成后，可以继续： -- [编译与运行](build-and-run.md) - 编译 SeekDB 项目 +- [编译与运行](build-and-run.md) - 编译 seekdb 项目 - [IDE 配置](ide-settings.md) - 配置开发环境以便更好地阅读代码 diff --git a/docs/developer-guide/zh/unittest.md b/docs/developer-guide/zh/unittest.md index 953cdd1e6..70994dee6 100644 --- a/docs/developer-guide/zh/unittest.md +++ b/docs/developer-guide/zh/unittest.md @@ -1,27 +1,27 @@ # 编写与运行单元测试 -本文档介绍如何在 OceanBase SeekDB 项目中编写和运行单元测试。 +本文档介绍如何在 OceanBase seekdb 项目中编写和运行单元测试。 ## 概述 -SeekDB 使用 [Google Test](https://github.com/google/googletest) 作为单元测试框架。单元测试代码位于项目根目录下的 `unittest` 目录中。 +seekdb 使用 [Google Test](https://github.com/google/googletest) 作为单元测试框架。单元测试代码位于项目根目录下的 `unittest` 目录中。 ## 相关文档 - [编译与运行](build-and-run.md) - 编译项目的基础 -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程风格 +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程风格 - [调试方法](debug.md) - 调试测试代码 ## 编译及运行所有单元测试 -SeekDB 有两个单元测试目录： +seekdb 有两个单元测试目录： - `unittest`：主要的单元测试用例，测试 `src` 目录中的代码 - `deps/oblib/unittest`：oblib 库的测试用例 ### 编译单元测试 -默认情况下，构建 SeekDB 项目时不会自动编译单元测试。需要显式编译： +默认情况下，构建 seekdb 项目时不会自动编译单元测试。需要显式编译： ```bash # 1. 首先编译项目（Debug 模式） @@ -78,7 +78,7 @@ find . -name "test_chunk_row_store" ### 测试文件命名 -SeekDB 使用 `test_xxx.cpp` 作为单元测试文件名。创建测试文件后，需要将文件名添加到对应的 `CMakeLists.txt` 文件中。 +seekdb 使用 `test_xxx.cpp` 作为单元测试文件名。创建测试文件后，需要将文件名添加到对应的 `CMakeLists.txt` 文件中。 ### 测试文件模板 @@ -142,7 +142,7 @@ TEST(RARowStore, alloc_project_fail) ### 更多信息 - [Google Test 文档](https://google.github.io/googletest/) - 了解 `TEST`、`ASSERT` 和 `EXPECT` 等宏的详细用法 -- [编程惯例](coding-convention.md) - 了解 SeekDB 的编程风格 +- [编程惯例](coding-convention.md) - 了解 seekdb 的编程风格 ## CI 中的单元测试 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e9ade1ef1..c578f0085 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -2,6 +2,7 @@ site_name: OceanBase seekdb Developer Guide site_url: https://oceanbase.github.io/seekdb repo_url: https://github.com/oceanbase/seekdb repo_name: oceanbase/seekdb +docs_dir: developer-guide plugins: - search #- material-relative-language-selector diff --git a/src/observer/omt/ob_multi_level_queue.h b/src/observer/omt/ob_multi_level_queue.h index 86358f438..691901658 100644 --- a/src/observer/omt/ob_multi_level_queue.h +++ b/src/observer/omt/ob_multi_level_queue.h @@ -20,7 +20,7 @@ #include "lib/queue/ob_priority_queue.h" #include "rpc/ob_request.h" /// TODO remove multi level queue -#define MULTI_LEVEL_QUEUE_SIZE (1) +#define MULTI_LEVEL_QUEUE_SIZE (5) #define MULTI_LEVEL_THRESHOLD (2) #define GROUP_MULTI_LEVEL_THRESHOLD (1) diff --git a/src/share/vector_index/ob_plugin_vector_index_adaptor.cpp b/src/share/vector_index/ob_plugin_vector_index_adaptor.cpp index 37e194490..6222b9cdc 100644 --- a/src/share/vector_index/ob_plugin_vector_index_adaptor.cpp +++ b/src/share/vector_index/ob_plugin_vector_index_adaptor.cpp @@ -2380,13 +2380,14 @@ int ObPluginVectorIndexAdaptor::complete_delta_buffer_table_data(ObVectorQueryAd LOG_WARN("failed to alloc sparse byte lens", K(ret), K(count)); } else { char *sparse_curr_pos = sparse_vectors; + int j = 0; // Copy the raw sparse vector data for (int i = 0; OB_SUCC(ret) && i < ctx->get_vec_cnt(); i++) { if (!ctx->vec_data_.vectors_[i].is_null() && !ctx->vec_data_.vectors_[i].get_string().empty()) { ObString vec_str = ctx->vec_data_.vectors_[i].get_string(); - memcpy(sparse_curr_pos, vec_str.ptr(), vec_str.length()); + MEMCPY(sparse_curr_pos, vec_str.ptr(), vec_str.length()); sparse_curr_pos += vec_str.length(); - sparse_byte_lens[i] = vec_str.length(); + sparse_byte_lens[j++] = vec_str.length(); } } diff --git a/src/storage/ddl/ob_ddl_pipeline.cpp b/src/storage/ddl/ob_ddl_pipeline.cpp index 3d35a5315..e400505aa 100644 --- a/src/storage/ddl/ob_ddl_pipeline.cpp +++ b/src/storage/ddl/ob_ddl_pipeline.cpp @@ -388,8 +388,13 @@ void ObVectorIndexTabletContext::destroy_ivf_build_helper() { int ret = OB_SUCCESS; if (nullptr != helper_) { - if (OB_FAIL(ObPluginVectorIndexUtils::release_vector_index_build_helper(helper_))) { - LOG_ERROR("fail to release vector index adapter", KR(ret)); + ObIAllocator *allocator = helper_->get_allocator(); + if (OB_ISNULL(allocator)) { + ret = OB_ERR_UNEXPECTED; + LOG_WARN("null allocator", K(ret)); + } else { + helper_->~ObIvfBuildHelper(); + allocator->free(helper_); } helper_ = nullptr; }