|
| 1 | +# Flow-IPC Sub-project -- SHM-jemalloc -- Commercial-grade jemalloc memory manager turbocharges your zero-copy work |
| 2 | + |
| 3 | +This project is a sub-project of the larger Flow-IPC meta-project. Please see |
| 4 | +a similar `README.md` for Flow-IPC, first. You can most likely find it either in the parent |
| 5 | +directory to this one; or else in a sibling GitHub repository named `ipc.git`. |
| 6 | + |
| 7 | +A more grounded description of the various sub-projects of Flow-IPC, including this one, can be found |
| 8 | +in `./src/ipc/common.hpp` off the directory containing the present README. Look for |
| 9 | +`Distributed sub-components (libraries)` in a large C++ comment. |
| 10 | + |
| 11 | +Took a look at those? Still interested in `ipc_shm` as an independent entity? Then read on. |
| 12 | +Before you do though: it is, typically, both easier and more functional to simply treat Flow-IPC as a whole. |
| 13 | +To do so it is sufficient to never have to delve into topics discussed in this README. In particular |
| 14 | +the Flow-IPC generated documentation guided Manual + Reference are monolithic and cover all the |
| 15 | +sub-projects together, including this one. |
| 16 | + |
| 17 | +Still interested? Then read on. |
| 18 | + |
| 19 | +`ipc_shm_arena_lend` depends on `ipc_shm` (and all its dependencies; i.e. `ipc_session`, `ipc_transport_structured`, |
| 20 | +`ipc_core`, `flow`). It provides `ipc::transport::struc::shm::arena_lend`, `ipc::shm::arena_lend`, and |
| 21 | +`ipc::session::shm::arena_lend`. |
| 22 | + |
| 23 | +`ipc_shm_arena_lend` (a/k/a **SHM-jemalloc**) adds an alternative **SHM-jemalloc SHM provider** to the one from |
| 24 | +its immediate dependency, `ipc_shm`, which provides the **SHM-classic SHM provider**. |
| 25 | +For most users, by changing the characters `classic` to `arena_lend::jemalloc` in a couple locations in |
| 26 | +your code, one will simply gain the properties of SHM-jemalloc. |
| 27 | + |
| 28 | + - Constructing (allocating) objects in shared memory (whether directly or indirectly, such as when |
| 29 | + creating `ipc::transport::struc::Msg_out`s for sending via `struc::Channel`), SHM-jemalloc will use |
| 30 | + the commercial-grade memory allocation provider, jemalloc (which powers Meta, FreeBSD, and many other |
| 31 | + huge things). You get thread caching, fragmentation avoidance -- all that good stuff that regular-heap |
| 32 | + `malloc()` and `new` gets you. By contrast SHM-classic (from `ipc_shm`) uses a reasonable but basic |
| 33 | + Boost-supplied allocation algorithm with few to no such perfomance-oriented features. (One can replace |
| 34 | + that algorithm, but it's not easy to do better: that's why things like jemalloc and tcmalloc exist and |
| 35 | + are no joke.) |
| 36 | + - The owner-segregated (a/k/a "arena-lending," hence the name) design of SHM-jemalloc enables a greater |
| 37 | + degree of safety which can matter a great deal in server situations with sensitive customer data. |
| 38 | + In the case of SHM-classic, both processes are reading and writing in the same SHM segment (**SHM pool**); |
| 39 | + if one crashes (among other things), both processes are "poisoned" w/r/t access to any data therein. |
| 40 | + Not so with SHM-jemalloc. (This is a hand-wavy description; rest assured the real documentation gets into |
| 41 | + all the desired details. Take a look at the guided Manual. See Documentation below.) |
| 42 | + |
| 43 | +## Installation |
| 44 | + |
| 45 | +An exported `ipc_shm_arena_lend` consists of C++ header files installed under "ipc/..." in the |
| 46 | +include-root; and a library such as `libipc_shm_arena_lend.a`. |
| 47 | +Certain items are also exported for people who use CMake to build their own |
| 48 | +projects; we make it particularly easy to use `ipc_shm_arena_lend` proper in that case |
| 49 | +(`find_package(IpcShmArenaLend)`). However documentation is generated monolithically for all of Flow-IPC; |
| 50 | +not for `ipc_shm_arena_lend` separately. |
| 51 | + |
| 52 | +The basic prerequisites for *building* the above: |
| 53 | + |
| 54 | + - Linux; |
| 55 | + - a C++ compiler with C++ 17 support; |
| 56 | + - Boost headers (plus certain libraries) install; |
| 57 | + - dependency headers and library (from within this overall project) install(s); in this case those of: |
| 58 | + `flow`, `ipc_core`, `ipc_transport_structured`, `ipc_session`, `ipc_shm`; |
| 59 | + - CMake; |
| 60 | + - Cap'n Proto (a/k/a capnp); |
| 61 | + - jemalloc. |
| 62 | + |
| 63 | +The basic prerequisites for *using* the above: |
| 64 | + |
| 65 | + - Linux, C++ compiler, Boost, above-listed dependency lib(s), capnp, jemalloc (but CMake is not required); plus: |
| 66 | + - your source code `#include`ing any exported `ipc/` headers must be itself built in C++ 17 mode; |
| 67 | + - any executable using the `ipc_*` libraries must be linked with certain Boost and ubiquitous |
| 68 | + system libraries. |
| 69 | + |
| 70 | +We intentionally omit version numbers and even specific compiler types in the above description; the CMake run |
| 71 | +should help you with that. |
| 72 | + |
| 73 | +To build `ipc_shm_arena_lend`: |
| 74 | + |
| 75 | + 1. Ensure a Boost install is available. If you don't have one, please install the latest version at |
| 76 | + [boost.org](https://boost.org). If you do have one, try using that one (our build will complain if insufficient). |
| 77 | + (From this point on, that's the recommended tactic to use when deciding on the version number for any given |
| 78 | + prerequisite. E.g., same deal with CMake in step 2.) |
| 79 | + 2. Ensure a CMake install is available (available at [CMake web site](https://cmake.org/download/) if needed). |
| 80 | + 3. Ensure a capnp install is available (available at [Cap'n Proto web site](https://capnproto.org/) if needed). |
| 81 | + 4. Ensure a jemalloc install is available (available at [jemalloc web site](https://jemalloc.net/) if needed). |
| 82 | + - If you are already using jemalloc in your under-development executable(s), great. We will work |
| 83 | + whether you're using it to replace default `malloc()`/`free()` and (orthogonally) `new`/`delete`; or |
| 84 | + not. |
| 85 | + - If you are *not* already using jemalloc: When building jemalloc, during its `configure` step, you |
| 86 | + have 2 choices to make. |
| 87 | + - Whether to replace default `malloc()`/`free()` in your application(s). This is entirely orthogonal |
| 88 | + to Flow-IPC's operation per se; rather it will affect general heap use in your application. |
| 89 | + Most likely converting your heap provider to jemalloc is a separate mission versus using Flow-IPC; |
| 90 | + so your answer will then be no, you don't want to replace `malloc()` and `free()`. In that case, |
| 91 | + when building jemalloc, use its `configure` feature wherein one supplies an API-name prefix to that |
| 92 | + script. |
| 93 | + - We recommend the prefix: `je_`. (Then the API will include `je_malloc()`, `je_free()`, and others.) |
| 94 | + - If you do (now, or later) intend to replace the default `malloc()`/`free()` with jemalloc's, then |
| 95 | + do not supply any prefix to `configure`. |
| 96 | + - Whether to replace `new`/`delete` (though the default impls may forward to `malloc()`/`free()`; in which |
| 97 | + case even if you do *not* replace them, the choice in the previous bullet will still have effect). |
| 98 | + This is a binary decision: Most likely, again, you don't want this replacement quite yet; |
| 99 | + so tell jemalloc's `configure` that via particular command-line flag. If you do, then tell `configure` |
| 100 | + *that*. |
| 101 | + - Flow-IPC will automatically build in the way compatible with the way you've built jemalloc. |
| 102 | + (Our CMake script(s) will, internally, use `jemalloc_config` program to determine the chosen API-name |
| 103 | + prefix.) |
| 104 | + 5. Use CMake `cmake` (command-line tool) or `ccmake` (interactive text-UI tool) to configure and generate |
| 105 | + a build system (namely a GNU-make `Makefile` and friends). Details on using CMake are outside our scope here; |
| 106 | + but the basics are as follows. CMake is very flexible and powerful; we've tried not to mess with that principle |
| 107 | + in our build script(s). |
| 108 | + 1. Choose a tool. `ccmake` will allow you to interactively configure aspects of the build system, including |
| 109 | + showing docs for various knobs our CMakeLists.txt (and friends) have made availale. `cmake` will do so without |
| 110 | + asking questions; you'll need to provide all required inputs on the command line. Let's assume `cmake` below, |
| 111 | + but you can use whichever makes sense for you. |
| 112 | + 2. Choose a working *build directory*, somewhere outside the present `ipc` distribution. Let's call this |
| 113 | + `$BUILD`: please `mkdir -p $BUILD`. Below we'll refer to the directory containing the present `README.md` file |
| 114 | + as `$SRC`. |
| 115 | + 3. Configure/generate the build system. The basic command line: |
| 116 | + `cd $BUILD && cmake -DCMAKE_INSTALL_PREFIX=... -DCMAKE_BUILD_TYPE=... $SRC`, |
| 117 | + where `$CMAKE_INSTALL_PREFIX/{include|lib|...}` will be the export location for headers/library/goodies; |
| 118 | + `CMAKE_BUILD_TYPE={Release|RelWithDebInfo|RelMinSize|Debug|}` specifies build config. |
| 119 | + More options are available -- `CMAKE_*` for CMake ones; `CFG_*` for Flow-IPC ones -- and can be |
| 120 | + viewed with `ccmake` or by glancing at `$BUILD/CMakeCache.txt` after running `cmake` or `ccmake`. |
| 121 | + - Regarding `CMAKE_BUILD_TYPE`, you can use the empty "" type to supply |
| 122 | + your own compile/link flags, such as if your organization or product has a standard set suitable for your |
| 123 | + situation. With the non-blank types we'll take CMake's sensible defaults -- which you can override |
| 124 | + as well. (See CMake docs; and/or a shortcut is checking out `$BUILD/CMakeCache.txt`.) |
| 125 | + - This is the likeliest stage at which CMake would detect lacking dependencies. See CMake docs for |
| 126 | + how to tweak its robust dependency-searching behavior; but generally if it's not in a global system |
| 127 | + location, or not in the `CMAKE_INSTALL_PREFIX` (export) location itself, then you can provide more |
| 128 | + search locations by adding a semicolon-separated list thereof via `-DCMAKE_PREFIX_PATH=...`. |
| 129 | + - Alternatively most things' locations can be individually specified via `..._DIR` settings. |
| 130 | + 4. Build using the build system generated in the preceding step: In `$BUILD` run `make`. |
| 131 | + 5. Install (export): In `$BUILD` run `make install`. |
| 132 | + |
| 133 | +To use `ipc_shm_arena_lend`: |
| 134 | + |
| 135 | + - `#include` the relevant exported header(s). |
| 136 | + - Link the exported library (such as `libipc_shm_arena_lend.a`) and the required other libraries to |
| 137 | + your executable(s). |
| 138 | + - If using CMake to build such executable(s): |
| 139 | + 1. Simply use `find_package(IpcShmArenaLend)` to find it. |
| 140 | + 2. Then use `target_link_libraries(... IpcShmArenaLend::ipc_shm_arena_lend)` on your target |
| 141 | + to ensure all necessary libraries are linked. |
| 142 | + (This will include the libraries themselves and the dependency libraries it needs to avoid undefined-reference |
| 143 | + errors when linking. Details on such things can be found in CMake documentation; and/or you may use |
| 144 | + our CMake script(s) for inspiration; after all we do build all the libraries and a `*_link_test.exec` |
| 145 | + executable.) |
| 146 | + - Otherwise specify it manually based on your build system of choice (if any). To wit, in order: |
| 147 | + - Link against `libipc_shm_arena_lend.a`, `libipc_shm.a`, `libipc_session.a`, `libipc_transport_structured.a`, |
| 148 | + `libipc_core.a`, and `libflow.a`. |
| 149 | + - Link against Boost libraries mentioned in a `flow/.../CMakeLists.txt` line (search `flow` dependency for it): |
| 150 | + `set(BOOST_LIBS ...)`. |
| 151 | + - Link against the system pthreads library, `librt`, and `libdl`. |
| 152 | + - Read the documentation to learn how to use Flow-IPC's (and/or Flow's) various features. |
| 153 | + (See Documentation below.) |
| 154 | + |
| 155 | +## Documentation |
| 156 | + |
| 157 | +See Flow-IPC meta-project's `README.md` Documentation section. `ipc_shm_arena_lend` lacks its own generated |
| 158 | +documentation. However, it contributes to the aforementioned monolithic documentation through its many comments which |
| 159 | +can (of course) be found directly in its code (`./src/ipc/...`). (The monolithic generated documentation scans |
| 160 | +these comments using Doxygen, combined with its siblings' comments... and so on.) |
| 161 | + |
| 162 | +## Contributing |
| 163 | + |
| 164 | +See Flow-IPC meta-project's `README.md` Contributing section. |
0 commit comments