Getting Started with the µOS++ Intrusive Lists
To address the specific needs of different audiences, this site features separate User's Guide, Contributor's Guide and Maintainer's Guide pages. This way, each group can easily find the information and resources most relevant to them.
Overview
The µOS++ Intrusive Lists project is a C++ source code library that implements the µOS++ intrusive doubly linked lists. These are special lists that avoid dynamic memory allocations by storing the links inside the list elements. This is particularly useful in embedded systems.
In this context, embedded refers exclusively to bare-metal systems, not embedded Linux, which necessitates a different approach for building Linux user-space applications.
The open-source µOS++ Intrusive Lists project is hosted on GitHub as
micro-os-plus/utils-lists-xpack.
As an npm/xpm package, the content is also published as
@micro-os-plus/utils-lists
on the npmjs.com repository
and can be integrated into projects as an xpm
dependency.
What are xpm packages? (xPacks)
xpm packages, abbreviated as xPacks, are versatile, language-neutral software packages. They have been successfully utilised in C/C++ projects.
What the heck are xpm packages (xPacks)? Please, do not introduce another package format!
Although the initial appearance may seem complex, utilising xpm packages is, in fact, straightforward. The design rationale is to automate frequent operations that occur during software development, such as the installation of dependencies, and to ensure reproducibility.
These packages are managed by xpm (the xPack Project Manager), a programme that complements the npm CLI (the popular JavaScript package manager), with new language-neutral features.
The xPacks Framework does NOT introduce a new package format; instead,
it uses the same format as npm packages, which is a collection of
files/folders and a package.json file with the package metadata.
xpm can install packages from the same repositories as npm, whether public or private.
The packages (usually regular archives, but also git repositories), are extracted into separate folders within the project.
Based on the content, there are two types of xpm packages:
- packages with source libraries (source xpm packages)
- packages with executables, usually platform-specific binary tools (binary xpm packages)
Source xpm packages are regular npm packages that include library source files, typically in C/C++, though there are no language restrictions.
Binary xpm packages are also regular npm packages, but with minimal
content, typically just the package.json file. Since these packages
provide executables for multiple platforms, some of which are quite
large, it is not practical to include all binaries within the npm
package itself. Instead, the package.json file contains references
(URLs) to platform-specific binary archives (e.g., .tar.gz for Unix or
.zip for Windows).
These archives are also expanded along with the package metadata.
Links/forwarders to
these executables are created in a .bin folder,
eliminating the need to add multiple folders to the PATH.
In summary, xpm packages can enhance and automate the installation process for source libraries and tools.
In summary, xpm packages can streamline and automate the installation process for source libraries and tools. Further details are available on the xpm Concepts page.
Features
The main features of the µOS++ Intrusive Lists are:
- The list links are embedded directly within the payload objects.
- Objects can belong to multiple lists simultaneously by maintaining multiple pairs of pointers, one for each list.
- They implement standard C++ iterators.
Benefits
- Completely avoid dynamic memory allocations.
- Reduce memory consumption by eliminating the links to the linked objects.
- Improve performance by removing the need to allocate and deallocate memory.
Install
The source code library can be installed automatically with xpm or manually, either by copying the relevant files into the target project, or by linking the entire project as a Git submodule.
The details for installing the µOS++ Intrusive Lists can be found in the Install Guide.
Status
The µOS++ Intrusive Lists project is fully functional, stable, and suitable for use in production environments.
Testing
The library is CI tested on every push via GitHub Actions, on Ubuntu, macOS, and Windows.
The tests run on 32 and 64-bit bare-metal platforms (Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, RV64IMAFDC), and natively, with GCC and LLVM/clang.
Release schedule
There are no scheduled releases; the project adheres to a continuous release approach, with updates deployed as development progresses.
Releases
The list of releases is available in the Releases pages.
Change log
The release and change log is available in the repository
CHANGELOG.md file.
Support & feedback
The quick advice for getting support and providing feedback is to use the GitHub Discussions.
For additional information, please refer to the Help Centre page.
Compatibility notices
According to SemVer rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
The breaking changes introduced by each major release, in reverse chronological order, are:
v4.x (2023)
Major rework; add double_list_links_base,
remove next() & previous() setters,
add initialize_once(), reorder double_list
template parameter, rename links_pointer().
v3.x (2022-04-04)
Rework, with templates instead of separate static classes and a cleaner API.
v2.x (2021-03-01)
The C++ namespace was renamed from os to micro_os_plus.
v1.x (2021-02-05)
The code was extracted from the mono-repo µOS++ project.
License
Unless otherwise stated, the original content is released under the terms of the MIT License, with all rights reserved by Liviu Ionescu.
This distortos is licensed under the terms of Mozilla Public License Version 2.0.
Credits
Many thanks to:
- distortos - for the inspiration on how these lists can be used in an RTOS
- Doxygen - for the site generator
- doxygen-awesome-css - for the nice Doxygen theme
- SVG REPO - for the SVG icons
Thanks to Shields IO for the badges.
Enjoyed Using This Project? Let Us Know!
If you enjoyed using this project, please let us know! Here are some ways you can show your support:
