Merge branch 'develop'

Author: MaJerle

.clang-format

@@ -122,8 +122,8 @@ ObjCBlockIndentWidth: 2
 ObjCBreakBeforeNestedBlockParam: true
 ObjCSpaceAfterProperty: false
 ObjCSpaceBeforeProtocolList: true
-PenaltyBreakAssignment: 2
-PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakAssignment: 50
+PenaltyBreakBeforeFirstCallParameter: 9
 PenaltyBreakComment: 300
 PenaltyBreakFirstLessLess: 120
 PenaltyBreakOpenParenthesis: 0

AUTHORS

@@ -1,9 +1,9 @@
 Tilen Majerle <[email protected]>
+Tofik Sonono <[email protected]>
+Jackistang <[email protected]>
 Tilen Majerle <[email protected]>
-Jaedeok Kim <[email protected]>
-Thomas Devoogdt <[email protected]>
-LinJieqiang <[email protected]>
-jnz86 <[email protected]>
 Junde Yhi <[email protected]>
-Jackistang <[email protected]>
-Tofik Sonono <[email protected]>
+jnz86 <[email protected]>
+LinJieqiang <[email protected]>
+Thomas Devoogdt <[email protected]>
+Jaedeok Kim <[email protected]>

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Develop
 
+## v3.2.0
+
+- Add user argument option
+- Improve the variable names to better conform *LLVM* tidy config
+
 ## v3.1.0
 
 - Preparation for `v3.1`
@@ -17,7 +22,7 @@
 - Add `lwrb_move` and `lwrb_overwrite`
 - Fix `lwrb_find` which failed to properly search for tokens at corner cases
 
-## v3.1.0-RC1
+## v3.0.0-RC1
 
 - Split CMakeLists.txt files between library and executable
 - Change license year to 2022

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Tilen MAJERLE
+Copyright (c) 2024 Tilen MAJERLE
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

dev/main.c

@@ -36,9 +36,9 @@ main() {
 
 #define RW_TEST(_w_exp_, _r_exp_, _rw_len_, _rw_exp_len_)                                                              \
     do {                                                                                                               \
-        printf("W ptr: %u, R ptr: %u, R/W len: %u, as_expected: %u\r\n", (unsigned)buff.w, (unsigned)buff.r,           \
+        printf("W ptr: %u, R ptr: %u, R/W len: %u, as_expected: %u\r\n", (unsigned)buff.w_ptr, (unsigned)buff.r_ptr,   \
                (unsigned)(_rw_len_),                                                                                   \
-               (unsigned)(buff.w == (_w_exp_) && buff.r == (_r_exp_) && (_rw_len_) == (_rw_exp_len_)));                \
+               (unsigned)(buff.w_ptr == (_w_exp_) && buff.r_ptr == (_r_exp_) && (_rw_len_) == (_rw_exp_len_)));        \
     } while (0)
 
         lwrb_reset(&buff);
@@ -65,9 +65,9 @@ main() {
 
 #define RW_TEST(_w_exp_, _r_exp_, _success_, _rw_len_, _rw_exp_len_)                                                   \
     do {                                                                                                               \
-        printf("W ptr: %u, R ptr: %u, R/W success: %u, R/W len: %u, as_expected: %u\r\n", (unsigned)buff.w,            \
-               (unsigned)buff.r, (unsigned)(_success_), (unsigned)(_rw_len_),                                          \
-               (unsigned)(buff.w == (_w_exp_) && buff.r == (_r_exp_) && (_rw_len_) == (_rw_exp_len_)));                \
+        printf("W ptr: %u, R ptr: %u, R/W success: %u, R/W len: %u, as_expected: %u\r\n", (unsigned)buff.w_ptr,        \
+               (unsigned)buff.r_ptr, (unsigned)(_success_), (unsigned)(_rw_len_),                                      \
+               (unsigned)(buff.w_ptr == (_w_exp_) && buff.r_ptr == (_r_exp_) && (_rw_len_) == (_rw_exp_len_)));        \
     } while (0)
 
         lwrb_reset(&buff);
@@ -190,8 +190,8 @@ main() {
         FIND_TEST("678", 3, 0, 1);
 
         /* Restart by setting write and read as empty with offset */
-        buff.w = 6;
-        buff.r = 6;
+        buff.w_ptr = 6;
+        buff.r_ptr = 6;
         lwrb_write(&buff, "12345678", 8);
 
         FIND_TEST("123", 3, 0, 1); /* Must find it */
@@ -200,8 +200,8 @@ main() {
 
         /* Restart by setting write and read as empty with offset */
         /* This should generate data for search in overflow mode */
-        buff.w = 8;
-        buff.r = 8;
+        buff.w_ptr = 8;
+        buff.r_ptr = 8;
         lwrb_write(&buff, "12345678", 8);
 
         FIND_TEST("1234", 3, 0, 1); /* Must find it */

docs/get-started/index.rst

@@ -57,22 +57,22 @@ Update cloned to latest version
 Add library to project
 ^^^^^^^^^^^^^^^^^^^^^^
 
-At this point it is assumed that you have successfully download library, either cloned it or from releases page.
+At this point it is assumed that you have successfully download library, either with ``git clone`` command or with manual download from the library releases page.
 Next step is to add the library to the project, by means of source files to compiler inputs and header files in search path.
 
 *CMake* is the main supported build system. Package comes with the ``CMakeLists.txt`` and ``library.cmake`` files, both located in the ``lwrb`` directory:
 
-* ``CMakeLists.txt``: Is a wrapper and only includes ``library.cmake`` file. It is used if target application uses ``add_subdirectory`` and then uses ``target_link_libraries`` to include the library in the project
-* ``library.cmake``: It is a fully configured set of variables. User must use ``include(path/to/library.cmake)`` to include the library and must manually add files/includes to the final target
+* ``library.cmake``: It is a fully configured set of variables and with library definition. User can include this file to the project file with ``include(path/to/library.cmake)`` and then manually use the variables provided by the file, such as list of source files, include paths or necessary compiler definitions. It is up to the user to properly use the this file on its own.
+* ``CMakeLists.txt``: It is a wrapper-only file and includes ``library.cmake`` file. It is used for when user wants to include the library to the main project by simply calling ``add_subdirectory`` **CMake** command, followed by ``target_link_libraries`` to add library as an external library.
 
 .. tip::
-    Open ``library.cmake`` file and manually analyze all the possible variables you can set for full functionality.
+    Open ``library.cmake`` and analyze the provided information. Among variables, you can also find list of all possible exposed libraries for the user.
 
 If you do not use the *CMake*, you can do the following:
 
 * Copy ``lwrb`` folder to your project, it contains library files
 * Add ``lwrb/src/include`` folder to `include path` of your toolchain. This is where `C/C++` compiler can find the files during compilation process. Usually using ``-I`` flag
-* Add source files from ``lwrb/src/`` folder to toolchain build. These files are built by `C/C++` compiler. CMake configuration comes with the library, allows users to include library in the project as **subdirectory** and **library**.y
+* Add source files from ``lwrb/src/`` folder to toolchain build. These files are built by `C/C++` compilery
 * Build the project
 
 Minimal example code

library.json

@@ -1,6 +1,6 @@
 {
     "name": "LwRB",
-    "version": "3.1.0",
+    "version": "3.2.0",
     "description": "Lightweight general purpose ring buffer with optimizations for embedded systems",
     "keywords": "buffer, ring buffer, library, rb, cyclic",
     "repository": {

lwrb/library.cmake

@@ -1,4 +1,6 @@
 # 
+# LIB_PREFIX: LWRB
+#
 # This file provides set of variables for end user
 # and also generates one (or more) libraries, that can be added to the project using target_link_libraries(...)
 #
@@ -8,6 +10,9 @@
 # LWRB_COMPILE_DEFINITIONS: If defined, it provides "-D" definitions to the library build
 #
 
+# Custom include directory
+set(LWRB_CUSTOM_INC_DIR ${CMAKE_CURRENT_BINARY_DIR}/lib_inc)
+
 # Library core sources
 set(lwrb_core_SRCS 
     ${CMAKE_CURRENT_LIST_DIR}/src/lwrb/lwrb.c
@@ -21,6 +26,7 @@ set(lwrb_ex_SRCS
 # Setup include directories
 set(lwrb_include_DIRS
     ${CMAKE_CURRENT_LIST_DIR}/src/include
+    ${LWPKT_CUSTOM_INC_DIR}
 )
 
 # Register library to the system

lwrb/src/include/lwrb/lwrb.h

@@ -4,7 +4,7 @@
  */
 
 /*
- * Copyright (c) 2023 Tilen MAJERLE
+ * Copyright (c) 2024 Tilen MAJERLE
  *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
@@ -29,7 +29,7 @@
  * This file is part of LwRB - Lightweight ring buffer library.
  *
  * Author:          Tilen MAJERLE <[email protected]>
- * Version:         v3.1.0
+ * Version:         v3.2.0
  */
 #ifndef LWRB_HDR_H
 #define LWRB_HDR_H
@@ -99,25 +99,30 @@ typedef void (*lwrb_evt_fn)(struct lwrb* buff, lwrb_evt_type_t evt, lwrb_sz_t bp
 typedef struct lwrb {
     uint8_t* buff;  /*!< Pointer to buffer data. Buffer is considered initialized when `buff != NULL` and `size > 0` */
     lwrb_sz_t size; /*!< Size of buffer data. Size of actual buffer is `1` byte less than value holds */
-    lwrb_sz_atomic_t r; /*!< Next read pointer. Buffer is considered empty when `r == w` and full when `w == r - 1` */
-    lwrb_sz_atomic_t w; /*!< Next write pointer. Buffer is considered empty when `r == w` and full when `w == r - 1` */
-    lwrb_evt_fn evt_fn; /*!< Pointer to event callback function */
+    lwrb_sz_atomic_t r_ptr; /*!< Next read pointer.
+                                Buffer is considered empty when `r == w` and full when `w == r - 1` */
+    lwrb_sz_atomic_t w_ptr; /*!< Next write pointer.
+                                Buffer is considered empty when `r == w` and full when `w == r - 1` */
+    lwrb_evt_fn evt_fn;     /*!< Pointer to event callback function */
+    void* arg;              /*!< Event custom user argument */
 } lwrb_t;
 
 uint8_t lwrb_init(lwrb_t* buff, void* buffdata, lwrb_sz_t size);
 uint8_t lwrb_is_ready(lwrb_t* buff);
 void lwrb_free(lwrb_t* buff);
 void lwrb_reset(lwrb_t* buff);
 void lwrb_set_evt_fn(lwrb_t* buff, lwrb_evt_fn fn);
+void lwrb_set_arg(lwrb_t* buff, void* arg);
+void* lwrb_get_arg(lwrb_t* buff);
 
 /* Read/Write functions */
 lwrb_sz_t lwrb_write(lwrb_t* buff, const void* data, lwrb_sz_t btw);
 lwrb_sz_t lwrb_read(lwrb_t* buff, void* data, lwrb_sz_t btr);
 lwrb_sz_t lwrb_peek(const lwrb_t* buff, lwrb_sz_t skip_count, void* data, lwrb_sz_t btp);
 
 /* Extended read/write functions */
-uint8_t lwrb_write_ex(lwrb_t* buff, const void* data, lwrb_sz_t btw, lwrb_sz_t* bw, uint16_t flags);
-uint8_t lwrb_read_ex(lwrb_t* buff, void* data, lwrb_sz_t btr, lwrb_sz_t* br, uint16_t flags);
+uint8_t lwrb_write_ex(lwrb_t* buff, const void* data, lwrb_sz_t btw, lwrb_sz_t* bwritten, uint16_t flags);
+uint8_t lwrb_read_ex(lwrb_t* buff, void* data, lwrb_sz_t btr, lwrb_sz_t* bread, uint16_t flags);
 
 /* Buffer size information */
 lwrb_sz_t lwrb_get_free(const lwrb_t* buff);