mirror of
https://github.com/boostorg/redis.git
synced 2026-01-19 04:42:09 +00:00
Migrates the documentation to Asciidoc/MrDocs (#276)
Fixes some typos close #247
This commit is contained in:
Anarthal (Rubén Pérez)
committed by
GitHub
GitHub
parent
963ae8d145
commit
adf17f2b3b
26
doc/CMakeLists.txt
Normal file
26
doc/CMakeLists.txt
Normal file
@@ -0,0 +1,26 @@
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
# Root CMakeLists.txt so MrDocs knows how to build our code
|
||||
cmake_minimum_required(VERSION 3.8...3.22)
|
||||
|
||||
# Project
|
||||
project(boost_redis_mrdocs LANGUAGES CXX)
|
||||
|
||||
# MrDocs forces CMAKE_EXPORT_COMPILE_COMMANDS=ON, incorrectly
|
||||
# causing all targets to be dumped to the compilation database.
|
||||
# Disable this setting so we can set EXPORT_COMPILE_COMMANDS
|
||||
# only to our target of interest
|
||||
set(CMAKE_EXPORT_COMPILE_COMMANDS OFF)
|
||||
|
||||
# Add Boost
|
||||
add_subdirectory($ENV{BOOST_SRC_DIR} deps/boost)
|
||||
|
||||
# Add the target for mrdocs to analyze
|
||||
add_executable(mrdocs mrdocs.cpp)
|
||||
target_link_libraries(mrdocs PRIVATE Boost::redis)
|
||||
set_target_properties(mrdocs PROPERTIES EXPORT_COMPILE_COMMANDS ON)
|
||||
@@ -1,226 +0,0 @@
|
||||
<doxygenlayout version="1.0">
|
||||
<!-- Generated by doxygen 1.9.1 -->
|
||||
<!-- Navigation index tabs for HTML output -->
|
||||
<navindex>
|
||||
<tab type="mainpage" visible="yes" title="Contents"/>
|
||||
<tab type="pages" visible="yes" title="" intro=""/>
|
||||
<tab type="modules" visible="no" title="Reference" intro=""/>
|
||||
<tab type="namespaces" visible="no" title="">
|
||||
<tab type="namespacelist" visible="yes" title="" intro=""/>
|
||||
<tab type="namespacemembers" visible="yes" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="interfaces" visible="no" title="">
|
||||
<tab type="interfacelist" visible="yes" title="" intro=""/>
|
||||
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="classes" visible="no" title="">
|
||||
<tab type="classlist" visible="no" title="" intro=""/>
|
||||
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
<tab type="hierarchy" visible="no" title="" intro=""/>
|
||||
<tab type="classmembers" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="structs" visible="no" title="">
|
||||
<tab type="structlist" visible="no" title="" intro=""/>
|
||||
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
</tab>
|
||||
<tab type="exceptions" visible="no" title="">
|
||||
<tab type="exceptionlist" visible="no" title="" intro=""/>
|
||||
<tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
<tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="files" visible="no" title="">
|
||||
<tab type="filelist" visible="no" title="" intro=""/>
|
||||
<tab type="globals" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="examples" visible="yes" title="" intro=""/>
|
||||
</navindex>
|
||||
|
||||
<!-- Layout definition for a class page -->
|
||||
<class>
|
||||
<briefdescription visible="yes"/>
|
||||
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||
<inheritancegraph visible="$CLASS_GRAPH"/>
|
||||
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
|
||||
<memberdecl>
|
||||
<nestedclasses visible="yes" title=""/>
|
||||
<publictypes title=""/>
|
||||
<services title=""/>
|
||||
<interfaces title=""/>
|
||||
<publicslots title=""/>
|
||||
<signals title=""/>
|
||||
<publicmethods title=""/>
|
||||
<publicstaticmethods title=""/>
|
||||
<publicattributes title=""/>
|
||||
<publicstaticattributes title=""/>
|
||||
<protectedtypes title=""/>
|
||||
<protectedslots title=""/>
|
||||
<protectedmethods title=""/>
|
||||
<protectedstaticmethods title=""/>
|
||||
<protectedattributes title=""/>
|
||||
<protectedstaticattributes title=""/>
|
||||
<packagetypes title=""/>
|
||||
<packagemethods title=""/>
|
||||
<packagestaticmethods title=""/>
|
||||
<packageattributes title=""/>
|
||||
<packagestaticattributes title=""/>
|
||||
<properties title=""/>
|
||||
<events title=""/>
|
||||
<privatetypes title=""/>
|
||||
<privateslots title=""/>
|
||||
<privatemethods title=""/>
|
||||
<privatestaticmethods title=""/>
|
||||
<privateattributes title=""/>
|
||||
<privatestaticattributes title=""/>
|
||||
<friends title=""/>
|
||||
<related title="" subtitle=""/>
|
||||
<membergroups visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
<memberdef>
|
||||
<inlineclasses title=""/>
|
||||
<typedefs title=""/>
|
||||
<enums title=""/>
|
||||
<services title=""/>
|
||||
<interfaces title=""/>
|
||||
<constructors title=""/>
|
||||
<functions title=""/>
|
||||
<related title=""/>
|
||||
<variables title=""/>
|
||||
<properties title=""/>
|
||||
<events title=""/>
|
||||
</memberdef>
|
||||
<allmemberslink visible="yes"/>
|
||||
<usedfiles visible="$SHOW_USED_FILES"/>
|
||||
<authorsection visible="yes"/>
|
||||
</class>
|
||||
|
||||
<!-- Layout definition for a namespace page -->
|
||||
<namespace>
|
||||
<briefdescription visible="yes"/>
|
||||
<memberdecl>
|
||||
<nestednamespaces visible="yes" title=""/>
|
||||
<constantgroups visible="yes" title=""/>
|
||||
<interfaces visible="yes" title=""/>
|
||||
<classes visible="yes" title=""/>
|
||||
<structs visible="yes" title=""/>
|
||||
<exceptions visible="yes" title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
<membergroups visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
<memberdef>
|
||||
<inlineclasses title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
</memberdef>
|
||||
<authorsection visible="yes"/>
|
||||
</namespace>
|
||||
|
||||
<!-- Layout definition for a file page -->
|
||||
<file>
|
||||
<briefdescription visible="yes"/>
|
||||
<includes visible="$SHOW_INCLUDE_FILES"/>
|
||||
<includegraph visible="$INCLUDE_GRAPH"/>
|
||||
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
|
||||
<sourcelink visible="yes"/>
|
||||
<memberdecl>
|
||||
<interfaces visible="yes" title=""/>
|
||||
<classes visible="yes" title=""/>
|
||||
<structs visible="yes" title=""/>
|
||||
<exceptions visible="yes" title=""/>
|
||||
<namespaces visible="yes" title=""/>
|
||||
<constantgroups visible="yes" title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
<membergroups visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
<memberdef>
|
||||
<inlineclasses title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
</memberdef>
|
||||
<authorsection/>
|
||||
</file>
|
||||
|
||||
<!-- Layout definition for a group page -->
|
||||
<group>
|
||||
<briefdescription visible="yes"/>
|
||||
<groupgraph visible="$GROUP_GRAPHS"/>
|
||||
<memberdecl>
|
||||
<nestedgroups visible="yes" title=""/>
|
||||
<dirs visible="yes" title=""/>
|
||||
<files visible="yes" title=""/>
|
||||
<namespaces visible="yes" title=""/>
|
||||
<classes visible="yes" title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<enumvalues title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
<signals title=""/>
|
||||
<publicslots title=""/>
|
||||
<protectedslots title=""/>
|
||||
<privateslots title=""/>
|
||||
<events title=""/>
|
||||
<properties title=""/>
|
||||
<friends title=""/>
|
||||
<membergroups visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
<memberdef>
|
||||
<pagedocs/>
|
||||
<inlineclasses title=""/>
|
||||
<defines title=""/>
|
||||
<typedefs title=""/>
|
||||
<sequences title=""/>
|
||||
<dictionaries title=""/>
|
||||
<enums title=""/>
|
||||
<enumvalues title=""/>
|
||||
<functions title=""/>
|
||||
<variables title=""/>
|
||||
<signals title=""/>
|
||||
<publicslots title=""/>
|
||||
<protectedslots title=""/>
|
||||
<privateslots title=""/>
|
||||
<events title=""/>
|
||||
<properties title=""/>
|
||||
<friends title=""/>
|
||||
</memberdef>
|
||||
<authorsection visible="yes"/>
|
||||
</group>
|
||||
|
||||
<!-- Layout definition for a directory page -->
|
||||
<directory>
|
||||
<briefdescription visible="yes"/>
|
||||
<directorygraph visible="yes"/>
|
||||
<memberdecl>
|
||||
<dirs visible="yes"/>
|
||||
<files visible="yes"/>
|
||||
</memberdecl>
|
||||
<detaileddescription title=""/>
|
||||
</directory>
|
||||
</doxygenlayout>
|
||||
92
doc/Jamfile
92
doc/Jamfile
@@ -1,85 +1,17 @@
|
||||
project redis/doc ;
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
import doxygen ;
|
||||
import path ;
|
||||
import sequence ;
|
||||
# Adapted from Boost.Unordered
|
||||
make html/index.html : build_antora.sh : @run-script ;
|
||||
|
||||
# All paths must be absolute to work well with the Doxygen rules.
|
||||
path-constant this_dir : . ;
|
||||
path-constant target_dir : html ;
|
||||
path-constant redis_root_dir : .. ;
|
||||
path-constant include_dir : ../include ;
|
||||
path-constant examples_dir : ../example ;
|
||||
path-constant readme : ../README.md ;
|
||||
path-constant layout_file : DoxygenLayout.xml ;
|
||||
path-constant header : header.html ;
|
||||
path-constant footer : footer.html ;
|
||||
|
||||
local stylesheet_files = [ path.glob $(this_dir) : *.css ] ;
|
||||
local includes = [ path.glob-tree $(include_dir) : *.hpp *.cpp ] ;
|
||||
local examples = [ path.glob-tree $(examples_dir) : *.hpp *.cpp ] ;
|
||||
|
||||
# If passed directly, several HTML_EXTRA_STYLESHEET tags are generated,
|
||||
# which is not correct.
|
||||
local stylesheet_arg = [ sequence.join "\"$(stylesheet_files)\"" : " " ] ;
|
||||
|
||||
# The doxygen rule requires the target name to end in .html to generate HTML files
|
||||
doxygen doc.html
|
||||
:
|
||||
$(includes) $(examples) $(readme)
|
||||
:
|
||||
<doxygen:param>"PROJECT_NAME=Boost.Redis"
|
||||
<doxygen:param>PROJECT_NUMBER="1.84.0"
|
||||
<doxygen:param>PROJECT_BRIEF="A redis client library"
|
||||
<doxygen:param>"STRIP_FROM_PATH=\"$(redis_root_dir)\""
|
||||
<doxygen:param>"STRIP_FROM_INC_PATH=\"$(include_dir)\""
|
||||
<doxygen:param>BUILTIN_STL_SUPPORT=YES
|
||||
<doxygen:param>INLINE_SIMPLE_STRUCTS=YES
|
||||
<doxygen:param>HIDE_UNDOC_MEMBERS=YES
|
||||
<doxygen:param>HIDE_UNDOC_CLASSES=YES
|
||||
<doxygen:param>SHOW_HEADERFILE=YES
|
||||
<doxygen:param>SORT_BRIEF_DOCS=YES
|
||||
<doxygen:param>SORT_MEMBERS_CTORS_1ST=YES
|
||||
<doxygen:param>SHOW_FILES=NO
|
||||
<doxygen:param>SHOW_NAMESPACES=NO
|
||||
<doxygen:param>"LAYOUT_FILE=\"$(layout_file)\""
|
||||
<doxygen:param>WARN_IF_INCOMPLETE_DOC=YES
|
||||
<doxygen:param>FILE_PATTERNS="*.hpp *.cpp"
|
||||
<doxygen:param>EXCLUDE_SYMBOLS=std
|
||||
<doxygen:param>"USE_MDFILE_AS_MAINPAGE=\"$(readme)\""
|
||||
<doxygen:param>SOURCE_BROWSER=YES
|
||||
<doxygen:param>"HTML_HEADER=\"$(header)\""
|
||||
<doxygen:param>"HTML_FOOTER=\"$(footer)\""
|
||||
<doxygen:param>"HTML_EXTRA_STYLESHEET=$(stylesheet_arg)"
|
||||
<doxygen:param>HTML_TIMESTAMP=YES
|
||||
<doxygen:param>GENERATE_TREEVIEW=YES
|
||||
<doxygen:param>FULL_SIDEBAR=YES
|
||||
<doxygen:param>DISABLE_INDEX=YES
|
||||
<doxygen:param>ENUM_VALUES_PER_LINE=0
|
||||
<doxygen:param>OBFUSCATE_EMAILS=YES
|
||||
<doxygen:param>USE_MATHJAX=YES
|
||||
<doxygen:param>MATHJAX_VERSION=MathJax_2
|
||||
<doxygen:param>MATHJAX_RELPATH="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/"
|
||||
<doxygen:param>MACRO_EXPANSION=YES
|
||||
<doxygen:param>HAVE_DOT=NO
|
||||
<doxygen:param>CLASS_GRAPH=NO
|
||||
<doxygen:param>DIRECTORY_GRAPH=NO
|
||||
;
|
||||
|
||||
explicit doc.html ;
|
||||
|
||||
# The doxygen rule only informs b2 about the main HTML file, and not about
|
||||
# all the doc directory that gets generated. Using the install rule copies
|
||||
# only a single file, which is incorrect. This is a workaround to copy
|
||||
# the generated docs to the doc/html directory, where they should be.
|
||||
make copyhtml.tag : doc.html : @copy_html_dir ;
|
||||
explicit copyhtml.tag ;
|
||||
actions copy_html_dir
|
||||
# Runs the Antora script
|
||||
actions run-script
|
||||
{
|
||||
rm -rf $(target_dir)
|
||||
mkdir -p $(target_dir)
|
||||
cp -r $(<:D)/html/doc/* $(target_dir)/
|
||||
echo "Stamped" > "$(<)"
|
||||
bash -x $(>)
|
||||
}
|
||||
|
||||
# These are used to inform the build system of the
|
||||
@@ -88,5 +20,5 @@ actions copy_html_dir
|
||||
alias boostdoc ;
|
||||
explicit boostdoc ;
|
||||
|
||||
alias boostrelease : copyhtml.tag ;
|
||||
alias boostrelease : html/index.html ;
|
||||
explicit boostrelease ;
|
||||
|
||||
15
doc/antora.yml
Normal file
15
doc/antora.yml
Normal file
@@ -0,0 +1,15 @@
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
name: redis
|
||||
title: Boost.Redis
|
||||
version: ~
|
||||
nav:
|
||||
- modules/ROOT/nav.adoc
|
||||
ext:
|
||||
cpp-reference:
|
||||
config: doc/mrdocs.yml
|
||||
19
doc/build_antora.sh
Executable file
19
doc/build_antora.sh
Executable file
@@ -0,0 +1,19 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
|
||||
cd "$SCRIPT_DIR"
|
||||
|
||||
# Required by our CMake.
|
||||
# Prevents Antora from cloning Boost again
|
||||
export BOOST_SRC_DIR=$(realpath $SCRIPT_DIR/../../..)
|
||||
|
||||
npm ci
|
||||
npx antora --log-format=pretty redis-playbook.yml
|
||||
@@ -1,145 +0,0 @@
|
||||
/**
|
||||
|
||||
Doxygen Awesome
|
||||
https://github.com/jothepro/doxygen-awesome-css
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2021 jothepro
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
*/
|
||||
|
||||
html {
|
||||
/* side nav width. MUST be = `TREEVIEW_WIDTH`.
|
||||
* Make sure it is wide enough to contain the page title (logo + title + version)
|
||||
*/
|
||||
--side-nav-fixed-width: 335px;
|
||||
}
|
||||
|
||||
#projectname {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
#page-wrapper {
|
||||
height: calc(100vh - 100px);
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
#content-wrapper {
|
||||
display: flex;
|
||||
flex-direction: row;
|
||||
min-height: 0;
|
||||
}
|
||||
|
||||
#doc-content {
|
||||
overflow-y: scroll;
|
||||
flex: 1;
|
||||
height: auto !important;
|
||||
}
|
||||
|
||||
@media (min-width: 768px) {
|
||||
html {
|
||||
--searchbar-background: var(--page-background-color);
|
||||
}
|
||||
|
||||
#sidebar-wrapper {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
min-width: var(--side-nav-fixed-width);
|
||||
max-width: var(--side-nav-fixed-width);
|
||||
background-color: var(--side-nav-background);
|
||||
border-right: 1px solid rgb(222, 222, 222);
|
||||
}
|
||||
|
||||
#search-box-wrapper {
|
||||
display: flex;
|
||||
flex-direction: row;
|
||||
padding-left: 1em;
|
||||
padding-right: 1em;
|
||||
}
|
||||
|
||||
#MSearchBox {
|
||||
flex: 1;
|
||||
display: flex;
|
||||
padding-left: 1em;
|
||||
padding-right: 1em;
|
||||
}
|
||||
|
||||
|
||||
#MSearchBox .left {
|
||||
display: flex;
|
||||
flex: 1;
|
||||
position: static;
|
||||
align-items: center;
|
||||
justify-content: flex-start;
|
||||
width: auto;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
#MSearchBox .right {
|
||||
display: none;
|
||||
}
|
||||
|
||||
#MSearchSelect {
|
||||
padding-left: 0.75em;
|
||||
left: auto;
|
||||
background-repeat: no-repeat;
|
||||
}
|
||||
|
||||
#MSearchField {
|
||||
flex: 1;
|
||||
position: static;
|
||||
width: auto;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
#nav-tree {
|
||||
height: auto !important;
|
||||
}
|
||||
|
||||
#nav-sync {
|
||||
display: none;
|
||||
}
|
||||
|
||||
#top {
|
||||
display: block;
|
||||
border-bottom: none;
|
||||
max-width: var(--side-nav-fixed-width);
|
||||
background: var(--side-nav-background);
|
||||
}
|
||||
|
||||
.ui-resizable-handle {
|
||||
cursor: default;
|
||||
width: 1px !important;
|
||||
}
|
||||
|
||||
#MSearchResultsWindow {
|
||||
left: var(--spacing-medium) !important;
|
||||
right: auto;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
#sidebar-wrapper {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,19 +0,0 @@
|
||||
<!-- HTML footer for doxygen 1.9.1-->
|
||||
<!-- start footer part -->
|
||||
</div> <!-- close #content-wrapper -->
|
||||
<!--BEGIN GENERATE_TREEVIEW-->
|
||||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||||
<ul>
|
||||
$navpath
|
||||
<li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
|
||||
</ul>
|
||||
</div>
|
||||
<!--END GENERATE_TREEVIEW-->
|
||||
<!--BEGIN !GENERATE_TREEVIEW-->
|
||||
<hr class="footer"/><address class="footer"><small>
|
||||
$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
|
||||
</small></address>
|
||||
<!--END !GENERATE_TREEVIEW-->
|
||||
</div> <!-- #page-wrapper -->
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,61 +0,0 @@
|
||||
<!-- HTML header for doxygen 1.9.1-->
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen $doxygenversion"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
|
||||
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
||||
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
||||
$treeview
|
||||
$search
|
||||
$mathjax
|
||||
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
||||
$extrastylesheet
|
||||
</head>
|
||||
<body>
|
||||
<div id="page-wrapper">
|
||||
<div id="content-wrapper">
|
||||
<div id="sidebar-wrapper">
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
|
||||
<!--BEGIN TITLEAREA-->
|
||||
<div id="titlearea">
|
||||
<table cellspacing="0" cellpadding="0">
|
||||
<tbody>
|
||||
<tr style="height: 56px;">
|
||||
<!--BEGIN PROJECT_LOGO-->
|
||||
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
|
||||
<!--END PROJECT_LOGO-->
|
||||
<!--BEGIN PROJECT_NAME-->
|
||||
<td id="projectalign" style="padding-left: 0.5em;">
|
||||
<div id="projectname">$projectname
|
||||
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
|
||||
</div>
|
||||
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
||||
</td>
|
||||
<!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME-->
|
||||
<!--BEGIN PROJECT_BRIEF-->
|
||||
<td style="padding-left: 0.5em;">
|
||||
<div id="projectbrief">$projectbrief</div>
|
||||
</td>
|
||||
<!--END PROJECT_BRIEF-->
|
||||
<!--END !PROJECT_NAME-->
|
||||
<!--BEGIN DISABLE_INDEX-->
|
||||
<!--END DISABLE_INDEX-->
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<!--BEGIN SEARCHENGINE-->
|
||||
<div id="search-box-wrapper">
|
||||
$searchbox
|
||||
</div>
|
||||
<!--END SEARCHENGINE-->
|
||||
<!--END TITLEAREA-->
|
||||
<!-- end header part -->
|
||||
10
doc/modules/ROOT/nav.adoc
Normal file
10
doc/modules/ROOT/nav.adoc
Normal file
@@ -0,0 +1,10 @@
|
||||
* xref:index.adoc[Introduction]
|
||||
* xref:requests_responses.adoc[]
|
||||
* xref:serialization.adoc[]
|
||||
* xref:logging.adoc[]
|
||||
* xref:benchmarks.adoc[]
|
||||
* xref:comparison.adoc[]
|
||||
* xref:examples.adoc[]
|
||||
* xref:reference.adoc[Reference]
|
||||
* xref:acknowledgements.adoc[]
|
||||
* xref:changelog.adoc[]
|
||||
37
doc/modules/ROOT/pages/acknowledgements.adoc
Normal file
37
doc/modules/ROOT/pages/acknowledgements.adoc
Normal file
@@ -0,0 +1,37 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Acknowledgements
|
||||
|
||||
Acknowledgement to people that helped shape Boost.Redis
|
||||
|
||||
* Richard Hodges (https://github.com/madmongo1[madmongo1]): For very helpful support with Asio, the design of asynchronous programs, etc.
|
||||
* Vinícius dos Santos Oliveira (https://github.com/vinipsmaker[vinipsmaker]): For useful discussion about how Boost.Redis consumes buffers in the read operation.
|
||||
* Petr Dannhofer (https://github.com/Eddie-cz[Eddie-cz]): For helping me understand how the `AUTH` and `HELLO` command can influence each other.
|
||||
* Mohammad Nejati (https://github.com/ashtum[ashtum]): For pointing out scenarios where calls to `async_exec` should fail when the connection is lost.
|
||||
* Klemens Morgenstern (https://github.com/klemens-morgenstern[klemens-morgenstern]): For useful discussion about timeouts, cancellation, synchronous interfaces and general help with Asio.
|
||||
* Vinnie Falco (https://github.com/vinniefalco[vinniefalco]): For general suggestions about how to improve the code and the documentation.
|
||||
* Bram Veldhoen (https://github.com/bveldhoen[bveldhoen]): For contributing a Redis-streams example.
|
||||
|
||||
Also many thanks to all individuals that participated in the Boost
|
||||
review
|
||||
|
||||
* Zach Laine: https://lists.boost.org/Archives/boost/2023/01/253883.php
|
||||
* Vinnie Falco: https://lists.boost.org/Archives/boost/2023/01/253886.php
|
||||
* Christian Mazakas: https://lists.boost.org/Archives/boost/2023/01/253900.php
|
||||
* Ruben Perez: https://lists.boost.org/Archives/boost/2023/01/253915.php
|
||||
* Dmitry Arkhipov: https://lists.boost.org/Archives/boost/2023/01/253925.php
|
||||
* Alan de Freitas: https://lists.boost.org/Archives/boost/2023/01/253927.php
|
||||
* Mohammad Nejati: https://lists.boost.org/Archives/boost/2023/01/253929.php
|
||||
* Sam Hartsfield: https://lists.boost.org/Archives/boost/2023/01/253931.php
|
||||
* Miguel Portilla: https://lists.boost.org/Archives/boost/2023/01/253935.php
|
||||
* Robert A.H. Leahy: https://lists.boost.org/Archives/boost/2023/01/253928.php
|
||||
|
||||
The Reviews can be found at:
|
||||
https://lists.boost.org/Archives/boost/2023/01/date.php. The thread
|
||||
with the ACCEPT from the review manager can be found here:
|
||||
https://lists.boost.org/Archives/boost/2023/01/253944.php.
|
||||
95
doc/modules/ROOT/pages/benchmarks.adoc
Normal file
95
doc/modules/ROOT/pages/benchmarks.adoc
Normal file
@@ -0,0 +1,95 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Echo server benchmark
|
||||
|
||||
This document benchmarks the performance of TCP echo servers I
|
||||
implemented in different languages using different Redis clients. The
|
||||
main motivations for choosing an echo server are
|
||||
|
||||
* Simple to implement and does not require expertise level in most languages.
|
||||
* I/O bound: Echo servers have very low CPU consumption in general
|
||||
and therefore are excellent to measure how a program handles concurrent requests.
|
||||
* It simulates very well a typical backend in regard to concurrency.
|
||||
|
||||
I also imposed some constraints on the implementations
|
||||
|
||||
* It should be simple enough and not require writing too much code.
|
||||
* Favor the use standard idioms and avoid optimizations that require expert level.
|
||||
* Avoid the use of complex things like connection and thread pool.
|
||||
|
||||
To reproduce these results run one of the echo-server programs in one
|
||||
terminal and the
|
||||
https://github.com/boostorg/redis/blob/42880e788bec6020dd018194075a211ad9f339e8/benchmarks/cpp/asio/echo_server_client.cpp[echo-server-client] in another.
|
||||
|
||||
== Without Redis
|
||||
|
||||
First I tested a pure TCP echo server, i.e. one that sends the messages
|
||||
directly to the client without interacting with Redis. The result can
|
||||
be seen below
|
||||
|
||||
image::https://boostorg.github.io/redis/tcp-echo-direct.png[]
|
||||
|
||||
The tests were performed with a 1000 concurrent TCP connections on the
|
||||
localhost where latency is 0.07ms on average on my machine. On higher
|
||||
latency networks the difference among libraries is expected to
|
||||
decrease.
|
||||
|
||||
* I expected Libuv to have similar performance to Asio and Tokio.
|
||||
* I did expect nodejs to come a little behind given it is is
|
||||
javascript code. Otherwise I did expect it to have similar
|
||||
performance to libuv since it is the framework behind it.
|
||||
* Go did surprise me: faster than nodejs and libuv!
|
||||
|
||||
The code used in the benchmarks can be found at
|
||||
|
||||
* https://github.com/boostorg/redis/blob/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/cpp/asio/echo_server_direct.cpp[Asio]: A variation of https://github.com/chriskohlhoff/asio/blob/4915cfd8a1653c157a1480162ae5601318553eb8/asio/src/examples/cpp20/coroutines/echo_server.cpp[this Asio example].
|
||||
* https://github.com/boostorg/redis/tree/835a1decf477b09317f391eddd0727213cdbe12b/benchmarks/c/libuv[Libuv]: Taken from https://github.com/libuv/libuv/blob/06948c6ee502862524f233af4e2c3e4ca876f5f6/docs/code/tcp-echo-server/main.c[this Libuv example].
|
||||
* https://github.com/boostorg/redis/tree/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/rust/echo_server_direct[Tokio]: Taken from https://docs.rs/tokio/latest/tokio/[here].
|
||||
* https://github.com/boostorg/redis/tree/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/nodejs/echo_server_direct[Nodejs]
|
||||
* https://github.com/boostorg/redis/blob/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/go/echo_server_direct.go[Go]
|
||||
|
||||
== With Redis
|
||||
|
||||
This is similar to the echo server described above but messages are
|
||||
echoed by Redis and not by the echo-server itself, which acts
|
||||
as a proxy between the client and the Redis server. The results
|
||||
can be seen below
|
||||
|
||||
image::https://boostorg.github.io/redis/tcp-echo-over-redis.png[]
|
||||
|
||||
The tests were performed on a network where latency is 35ms on
|
||||
average, otherwise it uses the same number of TCP connections
|
||||
as the previous example.
|
||||
|
||||
As the reader can see, the Libuv and the Rust test are not depicted
|
||||
in the graph, the reasons are
|
||||
|
||||
* https://github.com/redis-rs/redis-rs[redis-rs]: This client
|
||||
comes so far behind that it can't even be represented together
|
||||
with the other benchmarks without making them look insignificant.
|
||||
I don't know for sure why it is so slow, I suppose it has
|
||||
something to do with its lack of automatic
|
||||
https://redis.io/docs/manual/pipelining/[pipelining] support.
|
||||
In fact, the more TCP connections I launch the worse its
|
||||
performance gets.
|
||||
|
||||
* Libuv: I left it out because it would require me writing to much
|
||||
c code. More specifically, I would have to use hiredis and
|
||||
implement support for pipelines manually.
|
||||
|
||||
The code used in the benchmarks can be found at
|
||||
|
||||
* https://github.com/boostorg/redis[Boost.Redis]: https://github.com/boostorg/redis/blob/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/examples/echo_server.cpp[code]
|
||||
* https://github.com/redis/node-redis[node-redis]: https://github.com/boostorg/redis/tree/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/nodejs/echo_server_over_redis[code]
|
||||
* https://github.com/go-redis/redis[go-redis]: https://github.com/boostorg/redis/blob/3fb018ccc6138d310ac8b73540391cdd8f2fdad6/benchmarks/go/echo_server_over_redis.go[code]
|
||||
|
||||
|
||||
== Conclusion
|
||||
|
||||
Redis clients have to support automatic pipelining to have competitive performance. For updates to this document follow https://github.com/boostorg/redis[].
|
||||
|
||||
397
doc/modules/ROOT/pages/changelog.adoc
Normal file
397
doc/modules/ROOT/pages/changelog.adoc
Normal file
@@ -0,0 +1,397 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Changelog
|
||||
|
||||
== Boost 1.88
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/233[233])
|
||||
To deal with keys that might not exits in the Redis server, the
|
||||
library supports `std::optional`, for example
|
||||
`response<std::optional<std::vector<std::string>>>`. In some cases
|
||||
however, such as the https://redis.io/docs/latest/commands/mget/[MGET] command,
|
||||
each element in the vector might be non exiting, now it is possible
|
||||
to specify a response as `response<std::optional<std::vector<std::optional<std::string>>>>`.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/225[225])
|
||||
Use `deferred` as the connection default completion token.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/128[128])
|
||||
Adds a new `async_exec` overload that allows passing response
|
||||
adapters. This makes it possible to receive Redis responses directly
|
||||
in custom data structures thereby avoiding unnecessary data copying.
|
||||
Thanks to Ruben Perez (@anarthal) for implementing this feature.
|
||||
|
||||
* There are also other multiple small improvements in this release,
|
||||
users can refer to the git history for more details.
|
||||
|
||||
== Boost 1.87
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/205[205])
|
||||
Improves reaction time to disconnection by using `wait_for_one_error`
|
||||
instead of `wait_for_all`. The function `connection::async_run` was
|
||||
also changed to return EOF to the user when that error is received
|
||||
from the server. That is a breaking change.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/210[210])
|
||||
Fixes the adapter of empty nested responses.
|
||||
|
||||
* (Issues https://github.com/boostorg/redis/issues/211[211] and https://github.com/boostorg/redis/issues/212[212])
|
||||
Fixes the reconnect loop that would hang under certain conditions,
|
||||
see the linked issues for more details.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/219[219])
|
||||
Changes the default log level from `disabled` to `debug`.
|
||||
|
||||
== Boost 1.85
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/170[170])
|
||||
Under load and on low-latency networks it is possible to start
|
||||
receiving responses before the write operation completed and while
|
||||
the request is still marked as staged and not written. This messes
|
||||
up with the heuristics that classifies responses as unsolicited or
|
||||
not.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/168[168]).
|
||||
Provides a way of passing a custom SSL context to the connection.
|
||||
The design here differs from that of Boost.Beast and Boost.MySql
|
||||
since in Boost.Redis the connection owns the context instead of only
|
||||
storing a reference to a user provided one. This is ok so because
|
||||
apps need only one connection for their entire application, which
|
||||
makes the overhead of one ssl-context per connection negligible.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/181[181]).
|
||||
See a detailed description of this bug in
|
||||
https://github.com/boostorg/redis/issues/181#issuecomment-1913346983[this comment].
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/182[182]).
|
||||
Sets `"default"` as the default value of `config::username`. This
|
||||
makes it simpler to use the `requirepass` configuration in Redis.
|
||||
|
||||
* (Issue https://github.com/boostorg/redis/issues/189[189]).
|
||||
Fixes narrowing conversion by using `std::size_t` instead of
|
||||
`std::uint64_t` for the sizes of bulks and aggregates. The code
|
||||
relies now on `std::from_chars` returning an error if a value
|
||||
greater than 32 is received on platforms on which the size
|
||||
of `std::size_t` is 32.
|
||||
|
||||
|
||||
== Boost 1.84 (First release in Boost)
|
||||
|
||||
* Deprecates the `async_receive` overload that takes a response. Users
|
||||
should now first call `set_receive_response` to avoid constantly and
|
||||
unnecessarily setting the same response.
|
||||
|
||||
* Uses `std::function` to type erase the response adapter. This change
|
||||
should not influence users in any way but allowed important
|
||||
simplification in the connections internals. This resulted in
|
||||
massive performance improvement.
|
||||
|
||||
* The connection has a new member `get_usage()` that returns the
|
||||
connection usage information, such as number of bytes written,
|
||||
received etc.
|
||||
|
||||
* There are massive performance improvements in the consuming of
|
||||
server pushes which are now communicated with an `asio::channel` and
|
||||
therefore can be buffered which avoids blocking the socket read-loop.
|
||||
Batch reads are also supported by means of `channel.try_send` and
|
||||
buffered messages can be consumed synchronously with
|
||||
`connection::receive`. The function `boost::redis::cancel_one` has
|
||||
been added to simplify processing multiple server pushes contained
|
||||
in the same `generic_response`. *IMPORTANT*: These changes may
|
||||
result in more than one push in the response when
|
||||
`connection::async_receive` resumes. The user must therefore be
|
||||
careful when calling `resp.clear()`: either ensure that all message
|
||||
have been processed or just use `consume_one`.
|
||||
|
||||
== v1.4.2 (incorporates changes to conform the boost review and more)
|
||||
|
||||
* Adds `boost::redis::config::database_index` to make it possible to
|
||||
choose a database before starting running commands e.g. after an
|
||||
automatic reconnection.
|
||||
|
||||
* Massive performance improvement. One of my tests went from
|
||||
140k req/s to 390k/s. This was possible after a parser
|
||||
simplification that reduced the number of reschedules and buffer
|
||||
rotations.
|
||||
|
||||
* Adds Redis stream example.
|
||||
|
||||
* Renames the project to Boost.Redis and moves the code into namespace
|
||||
`boost::redis`.
|
||||
|
||||
* As pointed out in the reviews the `to_bulk` and `from_bulk` names were too
|
||||
generic for ADL customization points. They gained the prefix `boost_redis_`.
|
||||
|
||||
* Moves `boost::redis::resp3::request` to `boost::redis::request`.
|
||||
|
||||
* Adds new typedef `boost::redis::response` that should be used instead of
|
||||
`std::tuple`.
|
||||
|
||||
* Adds new typedef `boost::redis::generic_response` that should be used instead
|
||||
of `std::vector<resp3::node<std::string>>`.
|
||||
|
||||
* Renames `redis::ignore` to `redis::ignore_t`.
|
||||
|
||||
* Changes `async_exec` to receive a `redis::response` instead of an adapter,
|
||||
namely, instead of passing `adapt(resp)` users should pass `resp` directly.
|
||||
|
||||
* Introduces `boost::redis::adapter::result` to store responses to commands
|
||||
including possible resp3 errors without losing the error diagnostic part. To
|
||||
access values now use `std::get<N>(resp).value()` instead of
|
||||
`std::get<N>(resp)`.
|
||||
|
||||
* Implements full-duplex communication. Before these changes the connection
|
||||
would wait for a response to arrive before sending the next one. Now requests
|
||||
are continuously coalesced and written to the socket. `request::coalesce`
|
||||
became unnecessary and was removed. I could measure significative performance
|
||||
gains with these changes.
|
||||
|
||||
* Improves serialization examples using Boost.Describe to serialize to JSON and protobuf. See
|
||||
cpp20_json.cpp and cpp20_protobuf.cpp for more details.
|
||||
|
||||
* Upgrades to Boost 1.81.0.
|
||||
|
||||
* Fixes build with pass:[libc++].
|
||||
|
||||
* Adds high-level functionality to the connection classes. For
|
||||
example, `boost::redis::connection::async_run` will automatically
|
||||
resolve, connect, reconnect and perform health checks.
|
||||
|
||||
== v1.4.0-1
|
||||
|
||||
* Renames `retry_on_connection_lost` to `cancel_if_unresponded`. (v1.4.1)
|
||||
* Removes dependency on Boost.Hana, `boost::string_view`, Boost.Variant2 and Boost.Spirit.
|
||||
* Fixes build and setup CI on windows.
|
||||
|
||||
== v1.3.0-1
|
||||
|
||||
* Upgrades to Boost 1.80.0
|
||||
|
||||
* Removes automatic sending of the `HELLO` command. This can't be
|
||||
implemented properly without bloating the connection class. It is
|
||||
now a user responsibility to send HELLO. Requests that contain it have
|
||||
priority over other requests and will be moved to the front of the
|
||||
queue, see `aedis::request::config`
|
||||
|
||||
* Automatic name resolving and connecting have been removed from
|
||||
`aedis::connection::async_run`. Users have to do this step manually
|
||||
now. The reason for this change is that having them built-in doesn't
|
||||
offer enough flexibility that is need for boost users.
|
||||
|
||||
* Removes healthy checks and idle timeout. This functionality must now
|
||||
be implemented by users, see the examples. This is
|
||||
part of making Aedis useful to a larger audience and suitable for
|
||||
the Boost review process.
|
||||
|
||||
* The `aedis::connection` is now using a typeddef to a
|
||||
`net::ip::tcp::socket` and `aedis::ssl::connection` to
|
||||
`net::ssl::stream<net::ip::tcp::socket>`. Users that need to use
|
||||
other stream type must now specialize `aedis::basic_connection`.
|
||||
|
||||
* Adds a low level example of async code.
|
||||
|
||||
== v1.2.0
|
||||
|
||||
* `aedis::adapt` supports now tuples created with `std::tie`.
|
||||
`aedis::ignore` is now an alias to the type of `std::ignore`.
|
||||
|
||||
* Provides allocator support for the internal queue used in the
|
||||
`aedis::connection` class.
|
||||
|
||||
* Changes the behaviour of `async_run` to complete with success if
|
||||
asio::error::eof is received. This makes it easier to write
|
||||
composed operations with awaitable operators.
|
||||
|
||||
* Adds allocator support in the `aedis::request` (a
|
||||
contribution from Klemens Morgenstern).
|
||||
|
||||
* Renames `aedis::request::push_range2` to `push_range`. The
|
||||
suffix 2 was used for disambiguation. Klemens fixed it with SFINAE.
|
||||
|
||||
* Renames `fail_on_connection_lost` to
|
||||
`aedis::request::config::cancel_on_connection_lost`. Now, it will
|
||||
only cause connections to be canceled when `async_run` completes.
|
||||
|
||||
* Introduces `aedis::request::config::cancel_if_not_connected` which will
|
||||
cause a request to be canceled if `async_exec` is called before a
|
||||
connection has been established.
|
||||
|
||||
* Introduces new request flag `aedis::request::config::retry` that if
|
||||
set to true will cause the request to not be canceled when it was
|
||||
sent to Redis but remained unresponded after `async_run` completed.
|
||||
It provides a way to avoid executing commands twice.
|
||||
|
||||
* Removes the `aedis::connection::async_run` overload that takes
|
||||
request and adapter as parameters.
|
||||
|
||||
* Changes the way `aedis::adapt()` behaves with
|
||||
`std::vector<aedis::resp3::node<T>>`. Receiving RESP3 simple errors,
|
||||
blob errors or null won't causes an error but will be treated as
|
||||
normal response. It is the user responsibility to check the content
|
||||
in the vector.
|
||||
|
||||
* Fixes a bug in `connection::cancel(operation::exec)`. Now this
|
||||
call will only cancel non-written requests.
|
||||
|
||||
* Implements per-operation implicit cancellation support for
|
||||
`aedis::connection::async_exec`. The following call will `co_await (conn.async_exec(...) || timer.async_wait(...))`
|
||||
will cancel the request as long as it has not been written.
|
||||
|
||||
* Changes `aedis::connection::async_run` completion signature to
|
||||
`f(error_code)`. This is how is was in the past, the second
|
||||
parameter was not helpful.
|
||||
|
||||
* Renames `operation::receive_push` to `aedis::operation::receive`.
|
||||
|
||||
== v1.1.0-1
|
||||
|
||||
* Removes `coalesce_requests` from the `aedis::connection::config`, it
|
||||
became a request property now, see `aedis::request::config::coalesce`.
|
||||
|
||||
* Removes `max_read_size` from the `aedis::connection::config`. The maximum
|
||||
read size can be specified now as a parameter of the
|
||||
`aedis::adapt()` function.
|
||||
|
||||
* Removes `aedis::sync` class, see intro_sync.cpp for how to perform
|
||||
synchronous and thread safe calls. This is possible in Boost. 1.80
|
||||
only as it requires `boost::asio::deferred`.
|
||||
|
||||
* Moves from `boost::optional` to `std::optional`. This is part of
|
||||
moving to pass:[C++17].
|
||||
|
||||
* Changes the behaviour of the second `aedis::connection::async_run` overload
|
||||
so that it always returns an error when the connection is lost.
|
||||
|
||||
* Adds TLS support, see intro_tls.cpp.
|
||||
|
||||
* Adds an example that shows how to resolve addresses over sentinels,
|
||||
see subscriber_sentinel.cpp.
|
||||
|
||||
* Adds a `aedis::connection::timeouts::resp3_handshake_timeout`. This is
|
||||
timeout used to send the `HELLO` command.
|
||||
|
||||
* Adds `aedis::endpoint` where in addition to host and port, users can
|
||||
optionally provide username, password and the expected server role
|
||||
(see `aedis::error::unexpected_server_role`).
|
||||
|
||||
* `aedis::connection::async_run` checks whether the server role received in
|
||||
the hello command is equal to the expected server role specified in
|
||||
`aedis::endpoint`. To skip this check let the role variable empty.
|
||||
|
||||
* Removes reconnect functionality from `aedis::connection`. It
|
||||
is possible in simple reconnection strategies but bloats the class
|
||||
in more complex scenarios, for example, with sentinel,
|
||||
authentication and TLS. This is trivial to implement in a separate
|
||||
coroutine. As a result the `enum event` and `async_receive_event`
|
||||
have been removed from the class too.
|
||||
|
||||
* Fixes a bug in `connection::async_receive_push` that prevented
|
||||
passing any response adapter other that `adapt(std::vector<node>)`.
|
||||
|
||||
* Changes the behaviour of `aedis::adapt()` that caused RESP3 errors
|
||||
to be ignored. One consequence of it is that `connection::async_run`
|
||||
would not exit with failure in servers that required authentication.
|
||||
|
||||
* Changes the behaviour of `connection::async_run` that would cause it
|
||||
to complete with success when an error in the
|
||||
`connection::async_exec` occurred.
|
||||
|
||||
* Ports the buildsystem from autotools to CMake.
|
||||
|
||||
== v1.0.0
|
||||
|
||||
* Adds experimental cmake support for windows users.
|
||||
|
||||
* Adds new class `aedis::sync` that wraps an `aedis::connection` in
|
||||
a thread-safe and synchronous API. All free functions from the
|
||||
`sync.hpp` are now member functions of `aedis::sync`.
|
||||
|
||||
* Split `aedis::connection::async_receive_event` in two functions, one
|
||||
to receive events and another for server side pushes, see
|
||||
`aedis::connection::async_receive_push`.
|
||||
|
||||
* Removes collision between `aedis::adapter::adapt` and
|
||||
`aedis::adapt`.
|
||||
|
||||
* Adds `connection::operation` enum to replace `cancel_*` member
|
||||
functions with a single cancel function that gets the operations
|
||||
that should be cancelled as argument.
|
||||
|
||||
* Bugfix: a bug on reconnect from a state where the `connection` object
|
||||
had unsent commands. It could cause `async_exec` to never
|
||||
complete under certain conditions.
|
||||
|
||||
* Bugfix: Documentation of `adapt()` functions were missing from
|
||||
Doxygen.
|
||||
|
||||
== v0.3.0
|
||||
|
||||
* Adds `experimental::exec` and `receive_event` functions to offer a
|
||||
thread safe and synchronous way of executing requests across
|
||||
threads. See `intro_sync.cpp` and `subscriber_sync.cpp` for
|
||||
examples.
|
||||
|
||||
* `connection::async_read_push` was renamed to `async_receive_event`.
|
||||
|
||||
* `connection::async_receive_event` is now being used to communicate
|
||||
internal events to the user, such as resolve, connect, push etc. For
|
||||
examples see cpp20_subscriber.cpp and `connection::event`.
|
||||
|
||||
* The `aedis` directory has been moved to `include` to look more
|
||||
similar to Boost libraries. Users should now replace `-I/aedis-path`
|
||||
with `-I/aedis-path/include` in the compiler flags.
|
||||
|
||||
* The `AUTH` and `HELLO` commands are now sent automatically. This change was
|
||||
necessary to implement reconnection. The username and password
|
||||
used in `AUTH` should be provided by the user on
|
||||
`connection::config`.
|
||||
|
||||
* Adds support for reconnection. See `connection::enable_reconnect`.
|
||||
|
||||
* Fixes a bug in the `connection::async_run(host, port)` overload
|
||||
that was causing crashes on reconnection.
|
||||
|
||||
* Fixes the executor usage in the connection class. Before these
|
||||
changes it was imposing `any_io_executor` on users.
|
||||
|
||||
* `connection::async_receiver_event` is not cancelled anymore when
|
||||
`connection::async_run` exits. This change makes user code simpler.
|
||||
|
||||
* `connection::async_exec` with host and port overload has been
|
||||
removed. Use the other `connection::async_run` overload.
|
||||
|
||||
* The host and port parameters from `connection::async_run` have been
|
||||
move to `connection::config` to better support authentication and
|
||||
failover.
|
||||
|
||||
* Many simplifications in the `chat_room` example.
|
||||
|
||||
* Fixes build in clang the compilers and makes some improvements in
|
||||
the documentation.
|
||||
|
||||
== v0.2.0-1
|
||||
|
||||
* Fixes a bug that happens on very high load. (v0.2.1)
|
||||
* Major rewrite of the high-level API. There is no more need to use the low-level API anymore.
|
||||
* No more callbacks: Sending requests follows the ASIO asynchronous model.
|
||||
* Support for reconnection: Pending requests are not canceled when a connection is lost and are re-sent when a new one is established.
|
||||
* The library is not sending HELLO-3 on user behalf anymore. This is important to support AUTH properly.
|
||||
|
||||
== v0.1.0-2
|
||||
|
||||
* Adds reconnect coroutine in the `echo_server` example. (v0.1.2)
|
||||
* Corrects `client::async_wait_for_data` with `make_parallel_group` to launch operation. (v0.1.2)
|
||||
* Improvements in the documentation. (v0.1.2)
|
||||
* Avoids dynamic memory allocation in the client class after reconnection. (v0.1.2)
|
||||
* Improves the documentation and adds some features to the high-level client. (v.0.1.1)
|
||||
* Improvements in the design and documentation.
|
||||
|
||||
== v0.0.1
|
||||
|
||||
* First release to collect design feedback.
|
||||
|
||||
121
doc/modules/ROOT/pages/comparison.adoc
Normal file
121
doc/modules/ROOT/pages/comparison.adoc
Normal file
@@ -0,0 +1,121 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Comparison with other Redis clients
|
||||
|
||||
## Comparison
|
||||
|
||||
The main reason for why I started writing Boost.Redis was to have a client
|
||||
compatible with the Asio asynchronous model. As I made progresses I could
|
||||
also address what I considered weaknesses in other libraries. Due to
|
||||
time constraints I won't be able to give a detailed comparison with
|
||||
each client listed in the
|
||||
https://redis.io/docs/clients/#cpp[official list].
|
||||
Instead, I will focus on the most popular pass:[C++] client on github in number of stars, namely:
|
||||
|
||||
https://github.com/sewenew/redis-plus-plus[]
|
||||
|
||||
### Boost.Redis vs Redis-plus-plus
|
||||
|
||||
Before we start it is important to mention some of the things
|
||||
redis-plus-plus does not support
|
||||
|
||||
* The latest version of the communication protocol RESP3. Without that it is impossible to support some important Redis features like client side caching, among other things.
|
||||
* Coroutines.
|
||||
* Reading responses directly in user data structures to avoid creating temporaries.
|
||||
* Error handling with support for error-code.
|
||||
* Cancellation.
|
||||
|
||||
The remaining points will be addressed individually. Let us first
|
||||
have a look at what sending a command a pipeline and a transaction
|
||||
look like
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
auto redis = Redis("tcp://127.0.0.1:6379");
|
||||
|
||||
// Send commands
|
||||
redis.set("key", "val");
|
||||
auto val = redis.get("key"); // val is of type OptionalString.
|
||||
if (val)
|
||||
std::cout << *val << std::endl;
|
||||
|
||||
// Sending pipelines
|
||||
auto pipe = redis.pipeline();
|
||||
auto pipe_replies = pipe.set("key", "value")
|
||||
.get("key")
|
||||
.rename("key", "new-key")
|
||||
.rpush("list", {"a", "b", "c"})
|
||||
.lrange("list", 0, -1)
|
||||
.exec();
|
||||
|
||||
// Parse reply with reply type and index.
|
||||
auto set_cmd_result = pipe_replies.get<bool>(0);
|
||||
// ...
|
||||
|
||||
// Sending a transaction
|
||||
auto tx = redis.transaction();
|
||||
auto tx_replies = tx.incr("num0")
|
||||
.incr("num1")
|
||||
.mget({"num0", "num1"})
|
||||
.exec();
|
||||
|
||||
auto incr_result0 = tx_replies.get<long long>(0);
|
||||
// ...
|
||||
----
|
||||
|
||||
Some of the problems with this API are
|
||||
|
||||
* Heterogeneous treatment of commands, pipelines and transaction. This makes auto-pipelining impossible.
|
||||
* Any Api that sends individual commands has a very restricted scope of usability and should be avoided for performance reasons.
|
||||
* The API imposes exceptions on users, no error-code overload is provided.
|
||||
* No way to reuse the buffer for new calls to e.g. redis.get in order to avoid further dynamic memory allocations.
|
||||
* Error handling of resolve and connection not clear.
|
||||
|
||||
According to the documentation, pipelines in redis-plus-plus have
|
||||
the following characteristics
|
||||
|
||||
> +NOTE+: By default, creating a Pipeline object is NOT cheap, since
|
||||
> it creates a new connection.
|
||||
|
||||
This is clearly a downside in the API as pipelines should be the
|
||||
default way of communicating and not an exception, paying such a
|
||||
high price for each pipeline imposes a severe cost in performance.
|
||||
Transactions also suffer from the very same problem:
|
||||
|
||||
> +NOTE+: Creating a Transaction object is NOT cheap, since it
|
||||
> creates a new connection.
|
||||
|
||||
In Boost.Redis there is no difference between sending one command, a
|
||||
pipeline or a transaction because requests are decoupled
|
||||
from the I/O objects.
|
||||
|
||||
> redis-plus-plus also supports async interface, however, async
|
||||
> support for Transaction and Subscriber is still on the way.
|
||||
>
|
||||
> The async interface depends on third-party event library, and so
|
||||
> far, only libuv is supported.
|
||||
|
||||
Async code in redis-plus-plus looks like the following
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
auto async_redis = AsyncRedis(opts, pool_opts);
|
||||
|
||||
Future<string> ping_res = async_redis.ping();
|
||||
|
||||
cout << ping_res.get() << endl;
|
||||
----
|
||||
|
||||
As the reader can see, the async interface is based on futures
|
||||
which is also known to have a bad performance. The biggest
|
||||
problem however with this async design is that it makes it
|
||||
impossible to write asynchronous programs correctly since it
|
||||
starts an async operation on every command sent instead of
|
||||
enqueueing a message and triggering a write when it can be sent.
|
||||
It is also not clear how are pipelines realised with this design
|
||||
(if at all).
|
||||
27
doc/modules/ROOT/pages/examples.adoc
Normal file
27
doc/modules/ROOT/pages/examples.adoc
Normal file
@@ -0,0 +1,27 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Examples
|
||||
|
||||
The examples below show how to use the features discussed throughout this documentation:
|
||||
|
||||
* {site-url}/example/cpp20_intro.cpp[cpp20_intro.cpp]: Does not use awaitable operators.
|
||||
* {site-url}/example/cpp20_intro_tls.cpp[cpp20_intro_tls.cpp]: Communicates over TLS.
|
||||
* {site-url}/example/cpp20_unix_sockets.cpp[cpp20_unix_sockets.cpp]: Communicates over UNIX domain sockets.
|
||||
* {site-url}/example/cpp20_containers.cpp[cpp20_containers.cpp]: Shows how to send and receive STL containers and how to use transactions.
|
||||
* {site-url}/example/cpp20_json.cpp[cpp20_json.cpp]: Shows how to serialize types using Boost.Json.
|
||||
* {site-url}/example/cpp20_protobuf.cpp[cpp20_protobuf.cpp]: Shows how to serialize types using protobuf.
|
||||
* {site-url}/example/cpp20_resolve_with_sentinel.cpp[cpp20_resolve_with_sentinel.cpp]: Shows how to resolve a master address using sentinels.
|
||||
* {site-url}/example/cpp20_subscriber.cpp[cpp20_subscriber.cpp]: Shows how to implement pubsub with reconnection re-subscription.
|
||||
* {site-url}/example/cpp20_echo_server.cpp[cpp20_echo_server.cpp]: A simple TCP echo server.
|
||||
* {site-url}/example/cpp20_chat_room.cpp[cpp20_chat_room.cpp]: A command line chat built on Redis pubsub.
|
||||
* {site-url}/example/cpp17_intro.cpp[cpp17_intro.cpp]: Uses callbacks and requires pass:[C++17].
|
||||
* {site-url}/example/cpp17_intro_sync.cpp[cpp17_intro_sync.cpp]: Runs `async_run` in a separate thread and performs synchronous calls to `async_exec`.
|
||||
* {site-url}/example/cpp17_spdlog.cpp[cpp17_spdlog.cpp]: Shows how to use third-party logging libraries like `spdlog` with Boost.Redis.
|
||||
|
||||
The main function used in some async examples has been factored out in
|
||||
the {site-url}/example/main.cpp[main.cpp] file.
|
||||
143
doc/modules/ROOT/pages/index.adoc
Normal file
143
doc/modules/ROOT/pages/index.adoc
Normal file
@@ -0,0 +1,143 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
[#intro]
|
||||
= Introduction
|
||||
|
||||
Boost.Redis is a high-level https://redis.io/[Redis] client library built on top of
|
||||
https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html[Boost.Asio]
|
||||
that implements the Redis protocol
|
||||
https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md[RESP3].
|
||||
|
||||
== Requirements
|
||||
|
||||
The requirements for using Boost.Redis are:
|
||||
|
||||
* Boost 1.84 or higher. Boost.Redis is included in Boost installations since Boost 1.84.
|
||||
* pass:[C++17] or higher. Supported compilers include gcc 11 and later, clang 11 and later, and Visual Studio 16 (2019) and later.
|
||||
* Redis 6 or higher (must support RESP3).
|
||||
* OpenSSL.
|
||||
|
||||
The documentation assumes basic-level knowledge about https://redis.io/docs/[Redis] and https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html[Boost.Asio].
|
||||
|
||||
== Building the library
|
||||
|
||||
To use the library it is necessary to include the following:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
#include <boost/redis/src.hpp>
|
||||
----
|
||||
|
||||
in exactly one source file in your applications. Otherwise, the library is header-only.
|
||||
|
||||
Boost.Redis unconditionally requires OpenSSL. Targets using Boost.Redis need to link
|
||||
to the OpenSSL libraries.
|
||||
|
||||
== Tutorial
|
||||
|
||||
The code below uses a short-lived connection to
|
||||
https://redis.io/commands/ping/[ping] a Redis server:
|
||||
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
#include <boost/redis/connection.hpp>
|
||||
#include <boost/asio/co_spawn.hpp>
|
||||
#include <boost/asio/consign.hpp>
|
||||
#include <boost/asio/detached.hpp>
|
||||
#include <iostream>
|
||||
|
||||
namespace net = boost::asio;
|
||||
using boost::redis::request;
|
||||
using boost::redis::response;
|
||||
using boost::redis::config;
|
||||
using boost::redis::connection;
|
||||
|
||||
auto co_main(config const& cfg) -> net::awaitable<void>
|
||||
{
|
||||
auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
|
||||
conn->async_run(cfg, {}, net::consign(net::detached, conn));
|
||||
|
||||
// A request containing only a ping command.
|
||||
request req;
|
||||
req.push("PING", "Hello world");
|
||||
|
||||
// Response object.
|
||||
response<std::string> resp;
|
||||
|
||||
// Executes the request.
|
||||
co_await conn->async_exec(req, resp);
|
||||
conn->cancel();
|
||||
|
||||
std::cout << "PING: " << std::get<0>(resp).value() << std::endl;
|
||||
}
|
||||
----
|
||||
|
||||
The roles played by the `async_run` and `async_exec` functions are:
|
||||
|
||||
* xref:reference:boost/redis/basic_connection/async_exec-02.adoc[`connection::async_exec`]: executes the commands contained in the
|
||||
request and stores the individual responses in the response object. Can
|
||||
be called from multiple places in your code concurrently.
|
||||
* xref:reference:boost/redis/basic_connection/async_run-04.adoc[`connection::async_run`]: keeps the connection healthy. It takes care of hostname resolution, session establishment, health-checks, reconnection and coordination of low-level read and write operations. It should be called only once per connection, regardless of the number of requests to execute.
|
||||
|
||||
== Server pushes
|
||||
|
||||
Redis servers can also send a variety of pushes to the client. Some of
|
||||
them are:
|
||||
|
||||
* https://redis.io/docs/manual/pubsub/[Pubsub messages].
|
||||
* https://redis.io/docs/manual/keyspace-notifications/[Keyspace notifications].
|
||||
* https://redis.io/docs/manual/client-side-caching/[Client-side caching].
|
||||
|
||||
The connection class supports server pushes by means of the
|
||||
xref:reference:boost/redis/basic_connection/async_receive.adoc[`connection::async_receive`] function, which can be
|
||||
called in the same connection that is being used to execute commands.
|
||||
The coroutine below shows how to use it:
|
||||
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
auto
|
||||
receiver(std::shared_ptr<connection> conn) -> net::awaitable<void>
|
||||
{
|
||||
request req;
|
||||
req.push("SUBSCRIBE", "channel");
|
||||
|
||||
generic_response resp;
|
||||
conn->set_receive_response(resp);
|
||||
|
||||
// Loop while reconnection is enabled
|
||||
while (conn->will_reconnect()) {
|
||||
|
||||
// Reconnect to channels.
|
||||
co_await conn->async_exec(req, ignore);
|
||||
|
||||
// Loop reading Redis pushes.
|
||||
for (;;) {
|
||||
error_code ec;
|
||||
co_await conn->async_receive(resp, net::redirect_error(net::use_awaitable, ec));
|
||||
if (ec)
|
||||
break; // Connection lost, break so we can reconnect to channels.
|
||||
|
||||
// Use the response resp in some way and then clear it.
|
||||
...
|
||||
|
||||
consume_one(resp);
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== Further reading
|
||||
|
||||
Here is a list of topics that you might be interested in:
|
||||
|
||||
* xref:requests_responses.adoc[More on requests and responses].
|
||||
* xref:serialization.adoc[Serializing and parsing into custom types].
|
||||
* xref:logging.adoc[Configuring logging].
|
||||
* xref:examples.adoc[Examples].
|
||||
45
doc/modules/ROOT/pages/logging.adoc
Normal file
45
doc/modules/ROOT/pages/logging.adoc
Normal file
@@ -0,0 +1,45 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com),
|
||||
// Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Logging
|
||||
|
||||
xref:reference:boost/redis/basic_connection/async_run-04.adoc[`connection::async_run`]
|
||||
is a complex algorithm, with features like built-in reconnection.
|
||||
This can make configuration problems, like a misconfigured hostname, difficult to debug -
|
||||
Boost.Redis will keep retrying to connect to the same hostname over and over.
|
||||
For this reason, Boost.Redis incorporates a lightweight logging solution, and
|
||||
*will log some status messages to stderr by default*.
|
||||
|
||||
Logging can be customized by passing a
|
||||
xref:reference:boost/redis/logger.adoc[`logger`] object to the connection's constructor. For example, logging can be disabled by writing:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
asio::io_context ioc;
|
||||
connection conn {ioc, logger{logger::level::disabled}};
|
||||
----
|
||||
|
||||
Every message logged by the library is attached a
|
||||
https://en.wikipedia.org/wiki/Syslog#Severity_level[syslog-like severity]
|
||||
tag (a xref:reference:boost/redis/logger/level.adoc[`logger::level`]).
|
||||
You can filter messages by severity by creating a `logger` with a specific level:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
asio::io_context ioc;
|
||||
|
||||
// Logs to stderr messages with severity >= level::error.
|
||||
// This will hide all informational output.
|
||||
connection conn {ioc, logger{logger::level::error}};
|
||||
----
|
||||
|
||||
The `logger` constructor accepts a `std::function<void(logger::level, std::string_view)>`
|
||||
as second argument. If supplied, Boost.Redis will call this function when logging
|
||||
instead of printing to stderr. This can be used to integrate third-party logging
|
||||
libraries. See our {site-url}/example/cpp17_spdlog.cpp[spdlog integration example]
|
||||
for sample code.
|
||||
90
doc/modules/ROOT/pages/reference.adoc
Normal file
90
doc/modules/ROOT/pages/reference.adoc
Normal file
@@ -0,0 +1,90 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com),
|
||||
// Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
[#reference]
|
||||
= Reference
|
||||
|
||||
[width=100%,cols="5*"]
|
||||
|===
|
||||
|
||||
| *Connections*
|
||||
| *Requests and responses*
|
||||
| *Adapters*
|
||||
| *RESP3 protocol*
|
||||
| *Unstable low-level APIs*
|
||||
|
||||
|
|
||||
xref:reference:boost/redis/connection.adoc[`connection`]
|
||||
|
||||
xref:reference:boost/redis/basic_connection.adoc[`basic_connection`]
|
||||
|
||||
xref:reference:boost/redis/address.adoc[`address`]
|
||||
|
||||
xref:reference:boost/redis/config.adoc[`config`]
|
||||
|
||||
xref:reference:boost/redis/error.adoc[`error`]
|
||||
|
||||
xref:reference:boost/redis/logger.adoc[`logger`]
|
||||
|
||||
xref:reference:boost/redis/logger/level.adoc[`logger::level`]
|
||||
|
||||
xref:reference:boost/redis/operation.adoc[`operation`]
|
||||
|
||||
xref:reference:boost/redis/usage.adoc[`usage`]
|
||||
|
||||
|
||||
|
|
||||
xref:reference:boost/redis/ignore_t.adoc[`ignore_t`]
|
||||
|
||||
xref:reference:boost/redis/ignore.adoc[`ignore`]
|
||||
|
||||
xref:reference:boost/redis/request.adoc[`request`]
|
||||
|
||||
xref:reference:boost/redis/request/config.adoc[`request::config`]
|
||||
|
||||
xref:reference:boost/redis/response.adoc[`response`]
|
||||
|
||||
xref:reference:boost/redis/generic_response.adoc[`generic_response`]
|
||||
|
||||
xref:reference:boost/redis/consume_one-08.adoc[`consume_one`]
|
||||
|
||||
|
||||
|
|
||||
xref:reference:boost/redis/adapter/boost_redis_adapt.adoc[`boost_redis_adapt`]
|
||||
|
||||
xref:reference:boost/redis/adapter/ignore.adoc[`adapter::ignore`]
|
||||
|
||||
xref:reference:boost/redis/adapter/error.adoc[`adapter::error`]
|
||||
|
||||
xref:reference:boost/redis/adapter/result.adoc[`adapter::result`]
|
||||
|
||||
xref:reference:boost/redis/any_adapter.adoc[`any_adapter`]
|
||||
|
||||
|
|
||||
xref:reference:boost/redis/resp3/basic_node.adoc[`basic_node`]
|
||||
|
||||
xref:reference:boost/redis/resp3/node.adoc[`node`]
|
||||
|
||||
xref:reference:boost/redis/resp3/node_view.adoc[`node_view`]
|
||||
|
||||
xref:reference:boost/redis/resp3/boost_redis_to_bulk-08.adoc[`boost_redis_to_bulk`]
|
||||
|
||||
xref:reference:boost/redis/resp3/type.adoc[`type`]
|
||||
|
||||
xref:reference:boost/redis/resp3/is_aggregate.adoc[`is_aggregate`]
|
||||
|
||||
|
||||
|
|
||||
|
||||
xref:reference:boost/redis/adapter/adapt2.adoc[`adapter::adapt2`]
|
||||
|
||||
xref:reference:boost/redis/resp3/parser.adoc[`parser`]
|
||||
|
||||
xref:reference:boost/redis/resp3/parse.adoc[`parse`]
|
||||
|
||||
|===
|
||||
302
doc/modules/ROOT/pages/requests_responses.adoc
Normal file
302
doc/modules/ROOT/pages/requests_responses.adoc
Normal file
@@ -0,0 +1,302 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Requests and responses
|
||||
|
||||
== Requests
|
||||
|
||||
Redis requests are composed of one or more commands. In the
|
||||
Redis documentation, requests are called
|
||||
https://redis.io/topics/pipelining[pipelines]. For example:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
// Some example containers.
|
||||
std::list<std::string> list {...};
|
||||
std::map<std::string, mystruct> map { ...};
|
||||
|
||||
// The request can contain multiple commands.
|
||||
request req;
|
||||
|
||||
// Command with variable length of arguments.
|
||||
req.push("SET", "key", "some value", "EX", "2");
|
||||
|
||||
// Pushes a list.
|
||||
req.push_range("SUBSCRIBE", list);
|
||||
|
||||
// Same as above but as an iterator range.
|
||||
req.push_range("SUBSCRIBE", std::cbegin(list), std::cend(list));
|
||||
|
||||
// Pushes a map.
|
||||
req.push_range("HSET", "key", map);
|
||||
----
|
||||
|
||||
Sending a request to Redis is performed by
|
||||
xref:reference:boost/redis/basic_connection/async_exec-02.adoc[`connection::async_exec`]
|
||||
as already stated. Requests accept a xref:reference:boost/redis/request/config[`boost::redis::request::config`]
|
||||
object when constructed that dictates how requests are handled in situations like
|
||||
reconnection. The reader is advised to read it carefully.
|
||||
|
||||
## Responses
|
||||
|
||||
Boost.Redis uses the following strategy to deal with Redis responses:
|
||||
|
||||
* xref:reference:boost/redis/response.adoc[`boost::redis::response`] should be used
|
||||
when the request's number of commands is known at compile-time.
|
||||
* xref:reference:boost/redis/generic_response.adoc[`boost::redis::generic_response`] should be
|
||||
used when the number of commands is dynamic.
|
||||
|
||||
For example, the request below has three commands:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
request req;
|
||||
req.push("PING");
|
||||
req.push("INCR", "key");
|
||||
req.push("QUIT");
|
||||
----
|
||||
|
||||
Therefore, its response will also contain three elements.
|
||||
The following response object can be used:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
response<std::string, int, std::string>
|
||||
----
|
||||
|
||||
The response behaves as a `std::tuple` and must
|
||||
have as many elements as the request has commands (exceptions below).
|
||||
It is also necessary that each tuple element is capable of storing the
|
||||
response to the command it refers to, otherwise an error will occur.
|
||||
|
||||
To ignore responses to individual commands in the request use the tag
|
||||
xref:reference:boost/redis/ignore_t.adoc[`boost::redis::ignore_t`]. For example:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
// Ignore the second and last responses.
|
||||
response<std::string, ignore_t, std::string, ignore_t>
|
||||
----
|
||||
|
||||
The following table provides the RESP3-types returned by some Redis
|
||||
commands:
|
||||
|
||||
[cols="3*"]
|
||||
|===
|
||||
|
||||
| *Command* | *RESP3 type* | *Documentation*
|
||||
|
||||
| `lpush` | Number | https://redis.io/commands/lpush[]
|
||||
| `lrange` | Array | https://redis.io/commands/lrange[]
|
||||
| `set` | Simple-string, null or blob-string | https://redis.io/commands/set[]
|
||||
| `get` | Blob-string | https://redis.io/commands/get[]
|
||||
| `smembers` | Set | https://redis.io/commands/smembers[]
|
||||
| `hgetall` | Map | https://redis.io/commands/hgetall[]
|
||||
|
||||
|===
|
||||
|
||||
To map these RESP3 types into a pass:[C++] data structure use the table below:
|
||||
|
||||
[cols="3*"]
|
||||
|===
|
||||
|
||||
| *RESP3 type* | *Possible pass:[C++] type* | *Type*
|
||||
|
||||
| Simple-string | `std::string` | Simple
|
||||
| Simple-error | `std::string` | Simple
|
||||
| Blob-string | `std::string`, `std::vector` | Simple
|
||||
| Blob-error | `std::string`, `std::vector` | Simple
|
||||
| Number | `long long`, `int`, `std::size_t`, `std::string` | Simple
|
||||
| Double | `double`, `std::string` | Simple
|
||||
| Null | `std::optional<T>` | Simple
|
||||
| Array | `std::vector`, `std::list`, `std::array`, `std::deque` | Aggregate
|
||||
| Map | `std::vector`, `std::map`, `std::unordered_map` | Aggregate
|
||||
| Set | `std::vector`, `std::set`, `std::unordered_set` | Aggregate
|
||||
| Push | `std::vector`, `std::map`, `std::unordered_map` | Aggregate
|
||||
|
||||
|===
|
||||
|
||||
For example, the response to the request
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
request req;
|
||||
req.push("HELLO", 3);
|
||||
req.push_range("RPUSH", "key1", vec);
|
||||
req.push_range("HSET", "key2", map);
|
||||
req.push("LRANGE", "key3", 0, -1);
|
||||
req.push("HGETALL", "key4");
|
||||
req.push("QUIT");
|
||||
----
|
||||
|
||||
Can be read in the following response object:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
response<
|
||||
redis::ignore_t, // hello
|
||||
int, // rpush
|
||||
int, // hset
|
||||
std::vector<T>, // lrange
|
||||
std::map<U, V>, // hgetall
|
||||
std::string // quit
|
||||
> resp;
|
||||
----
|
||||
|
||||
To execute the request and read the response use
|
||||
xref:reference:boost/redis/basic_connection/async_exec-02.adoc[`async_exec`]:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
co_await conn->async_exec(req, resp);
|
||||
----
|
||||
|
||||
If the intention is to ignore responses altogether, use
|
||||
xref:reference:boost/redis/ignore.adoc[`ignore`]:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
// Ignores the response
|
||||
co_await conn->async_exec(req, ignore);
|
||||
----
|
||||
|
||||
Responses that contain nested aggregates or heterogeneous data
|
||||
types will be given special treatment later in xref:#the-general-case[the general case]. As
|
||||
of this writing, not all RESP3 types are used by the Redis server,
|
||||
which means in practice users will be concerned with a reduced
|
||||
subset of the RESP3 specification.
|
||||
|
||||
### Pushes
|
||||
|
||||
Commands that have no response, like
|
||||
|
||||
* `"SUBSCRIBE"`
|
||||
* `"PSUBSCRIBE"`
|
||||
* `"UNSUBSCRIBE"`
|
||||
|
||||
must **NOT** be included in the response tuple. For example, the following request
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
request req;
|
||||
req.push("PING");
|
||||
req.push("SUBSCRIBE", "channel");
|
||||
req.push("QUIT");
|
||||
----
|
||||
|
||||
must be read in the response object `response<std::string, std::string>`.
|
||||
|
||||
### Null
|
||||
|
||||
It is not uncommon for apps to access keys that do not exist or that
|
||||
have already expired in the Redis server. To deal with these use cases,
|
||||
wrap the type within a `std::optional`:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
response<
|
||||
std::optional<A>,
|
||||
std::optional<B>,
|
||||
...
|
||||
> resp;
|
||||
----
|
||||
|
||||
Everything else stays the same.
|
||||
|
||||
### Transactions
|
||||
|
||||
To read responses to transactions we must first observe that Redis
|
||||
will queue the transaction commands and send their individual
|
||||
responses as elements of an array. The array itself is the response to
|
||||
the `EXEC` command. For example, to read the response to this request
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
req.push("MULTI");
|
||||
req.push("GET", "key1");
|
||||
req.push("LRANGE", "key2", 0, -1);
|
||||
req.push("HGETALL", "key3");
|
||||
req.push("EXEC");
|
||||
----
|
||||
|
||||
Use the following response type:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
response<
|
||||
ignore_t, // multi
|
||||
ignore_t, // QUEUED
|
||||
ignore_t, // QUEUED
|
||||
ignore_t, // QUEUED
|
||||
response<
|
||||
std::optional<std::string>, // get
|
||||
std::optional<std::vector<std::string>>, // lrange
|
||||
std::optional<std::map<std::string, std::string>> // hgetall
|
||||
> // exec
|
||||
> resp;
|
||||
----
|
||||
|
||||
For a complete example, see {site-url}/example/cpp20_containers.cpp[cpp20_containers.cpp].
|
||||
|
||||
[#the-general-case]
|
||||
### The general case
|
||||
|
||||
There are cases where responses to Redis
|
||||
commands won't fit in the model presented above. Some examples are:
|
||||
|
||||
* Commands (like `set`) whose responses don't have a fixed
|
||||
RESP3 type. Expecting an `int` and receiving a blob-string
|
||||
results in an error.
|
||||
* RESP3 aggregates that contain nested aggregates can't be read in STL containers.
|
||||
* Transactions with a dynamic number of commands can't be read in a `response`.
|
||||
|
||||
To deal with these cases Boost.Redis provides the xref:reference:boost/redis/resp3/node.adoc[`boost::redis::resp3::node`] type
|
||||
abstraction, that is the most general form of an element in a
|
||||
response, be it a simple RESP3 type or the element of an aggregate. It
|
||||
is defined like:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
template <class String>
|
||||
struct basic_node {
|
||||
// The RESP3 type of the data in this node.
|
||||
type data_type;
|
||||
|
||||
// The number of elements of an aggregate (or 1 for simple data).
|
||||
std::size_t aggregate_size;
|
||||
|
||||
// The depth of this node in the response tree.
|
||||
std::size_t depth;
|
||||
|
||||
// The actual data. For aggregate types this is always empty.
|
||||
String value;
|
||||
};
|
||||
----
|
||||
|
||||
Any response to a Redis command can be parsed into a
|
||||
xref:reference:boost/redis/generic_response.adoc[boost::redis::generic_response].
|
||||
The vector can be seen as a pre-order view of the response tree.
|
||||
Using it is not different than using other types:
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
// Receives any RESP3 simple or aggregate data type.
|
||||
boost::redis::generic_response resp;
|
||||
co_await conn->async_exec(req, resp);
|
||||
----
|
||||
|
||||
For example, suppose we want to retrieve a hash data structure
|
||||
from Redis with `HGETALL`, some of the options are
|
||||
|
||||
* `boost::redis::generic_response`: always works.
|
||||
* `std::vector<std::string>`: efficient and flat, all elements as string.
|
||||
* `std::map<std::string, std::string>`: efficient if you need the data as a `std::map`.
|
||||
* `std::map<U, V>`: efficient if you are storing serialized data. Avoids temporaries and requires `boost_redis_from_bulk` for `U` and `V`.
|
||||
|
||||
In addition to the above users can also use unordered versions of the
|
||||
containers. The same reasoning applies to sets e.g. `SMEMBERS`
|
||||
and other data structures in general.
|
||||
26
doc/modules/ROOT/pages/serialization.adoc
Normal file
26
doc/modules/ROOT/pages/serialization.adoc
Normal file
@@ -0,0 +1,26 @@
|
||||
//
|
||||
// Copyright (c) 2025 Marcelo Zimbres Silva (mzimbres@gmail.com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
= Serializing and parsing into custom types
|
||||
|
||||
Boost.Redis supports serialization of user defined types by means of
|
||||
the following customization points
|
||||
|
||||
[source,cpp]
|
||||
----
|
||||
// Serialize
|
||||
void boost_redis_to_bulk(std::string& to, mystruct const& obj);
|
||||
|
||||
// Deserialize
|
||||
void boost_redis_from_bulk(mystruct& u, node_view const& node, boost::system::error_code&);
|
||||
----
|
||||
|
||||
These functions are accessed over ADL and therefore they must be
|
||||
imported in the global namespace by the user. The following examples might be of interest:
|
||||
|
||||
* {site-url}/example/cpp20_json.cpp[cpp20_json.cpp]: serializes and parses JSON objects.
|
||||
* {site-url}/example/cpp20_protobuf.cpp[cpp20_protobuf.cpp]: serializes and parses https://protobuf.dev/[protobuf] objects.
|
||||
10
doc/mrdocs.cpp
Normal file
10
doc/mrdocs.cpp
Normal file
@@ -0,0 +1,10 @@
|
||||
//
|
||||
// Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
|
||||
#define BOOST_ALLOW_DEPRECATED // avoid mrdocs errors with the BOOST_DEPRECATED macro
|
||||
|
||||
#include <boost/redis.hpp>
|
||||
31
doc/mrdocs.yml
Normal file
31
doc/mrdocs.yml
Normal file
@@ -0,0 +1,31 @@
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
source-root: ../include
|
||||
compilation-database: ./CMakeLists.txt
|
||||
include-symbols:
|
||||
- "boost::redis::**"
|
||||
exclude-symbols:
|
||||
- "boost::redis::detail::**"
|
||||
- "boost::redis::adapter::detail::**"
|
||||
- "boost::redis::resp3::detail::**"
|
||||
- "boost::redis::basic_connection::run_is_canceled"
|
||||
- "boost::redis::basic_connection::this_type"
|
||||
- "boost::redis::any_adapter::impl_t"
|
||||
- "boost::redis::any_adapter::fn_type"
|
||||
- "boost::redis::any_adapter::create_impl"
|
||||
- "boost::redis::any_adapter::impl_"
|
||||
- "boost::redis::request::payload"
|
||||
- "boost::redis::request::has_hello_priority"
|
||||
see-below:
|
||||
- "boost::redis::adapter::ignore"
|
||||
sort-members: false
|
||||
base-url: https://github.com/boostorg/redis/blob/master/include/
|
||||
use-system-libc: true
|
||||
warn-as-error: true
|
||||
warn-if-undocumented: false
|
||||
warn-no-paramdoc: false
|
||||
1955
doc/package-lock.json
generated
Normal file
1955
doc/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
6
doc/package.json
Normal file
6
doc/package.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"dependencies": {
|
||||
"@cppalliance/antora-cpp-reference-extension": "^0.0.6",
|
||||
"antora": "^3.1.10"
|
||||
}
|
||||
}
|
||||
45
doc/redis-playbook.yml
Normal file
45
doc/redis-playbook.yml
Normal file
@@ -0,0 +1,45 @@
|
||||
#
|
||||
# Copyright (c) 2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
site:
|
||||
url: https://github.com/boostorg/redis/blob/master
|
||||
title: Boost.Redis
|
||||
robots: allow
|
||||
start_page: redis::index.adoc
|
||||
|
||||
antora:
|
||||
extensions:
|
||||
- require: '@cppalliance/antora-cpp-reference-extension'
|
||||
dependencies:
|
||||
- name: 'boost'
|
||||
repo: 'https://github.com/boostorg/boost.git'
|
||||
tag: 'develop'
|
||||
variable: 'BOOST_SRC_DIR'
|
||||
system-env: 'BOOST_SRC_DIR'
|
||||
|
||||
asciidoc:
|
||||
attributes:
|
||||
# Scrolling problems appear without this
|
||||
page-pagination: ''
|
||||
|
||||
content:
|
||||
sources:
|
||||
- url: ..
|
||||
start_path: doc
|
||||
|
||||
ui:
|
||||
bundle:
|
||||
url: https://github.com/boostorg/website-v2-docs/releases/download/ui-master/ui-bundle.zip
|
||||
snapshot: true
|
||||
output_dir: _
|
||||
|
||||
output:
|
||||
dir: html
|
||||
|
||||
runtime:
|
||||
log:
|
||||
failure_level: error
|
||||
Reference in New Issue
Block a user