From 79c83eba7933f49e766dbeb85f9c40ee17e06edf Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 22 Dec 2021 12:35:36 +0100 Subject: Renamed csptr to carc. i_key/val_ref renamed to i_key/val_sptr. Change inspired by Rust Arc/Rc. cbox name is taken from Rust Box type. --- docs/cbox_api.md | 10 +++--- docs/csptr_api.md | 96 ++++++++++++++++++++++++++++--------------------------- 2 files changed, 54 insertions(+), 52 deletions(-) (limited to 'docs') diff --git a/docs/cbox_api.md b/docs/cbox_api.md index 011beea2..e05e69f0 100644 --- a/docs/cbox_api.md +++ b/docs/cbox_api.md @@ -1,4 +1,4 @@ -# STC [cbox](../include/stc/cbox.h): (Boxed) Heap Allocated Objects +# STC [cbox](../include/stc/cbox.h): Smart Pointer (Boxed object) **cbox** is a A box is a smart pointer to a heap allocated value of type X. A **cbox** can be empty. The *cbox_X_cmp()*, *cbox_X_drop()* methods are defined based on the `i_cmp` @@ -21,7 +21,7 @@ See similar c++ class [std::unique_ptr](https://en.cppreference.com/w/cpp/memory #define i_val // value: REQUIRED #define i_cmp // three-way compare two i_val* : REQUIRED IF i_val is a non-integral type #define i_drop // destroy value func - defaults to empty destruct -#define i_from // create from raw/clone func - REQUIRED if i_drop is defined, +#define i_from // create from raw/clone func - REQUIRED if i_drop is defined, // unless 'i_opt c_no_clone' is defined. #define i_tag // type name tag, defaults to i_val #include @@ -76,7 +76,7 @@ void int_drop(int* x) { // both for the cbox type and the container of cbox elements. It will also // disable emplace container functions. // -// This applies to all container types, except those with csptr elements, as they +// This applies to all container types, except those with carc elements, as they // define cloning internally. #define i_val int @@ -84,11 +84,11 @@ void int_drop(int* x) { #define i_from c_default_clone #include // cbox_int -#define i_key_bind cbox_int // note: use i_key_bind instead of i_key +#define i_key_sptr cbox_int // note: use i_key_sptr instead of i_key #define i_tag int // tag otherwise defaults to 'ref' #include // csset_int (like: std::set>) -#define i_val_bind cbox_int // note: use i_val_bind instead of i_val +#define i_val_sptr cbox_int // note: use i_val_sptr instead of i_val #define i_tag int // tag otherwise defaults to 'ref' #include // cvec_int (like: std::vector>) diff --git a/docs/csptr_api.md b/docs/csptr_api.md index 95575417..e33bf410 100644 --- a/docs/csptr_api.md +++ b/docs/csptr_api.md @@ -1,23 +1,24 @@ -# STC [csptr](../include/stc/csptr.h): Atomic Reference Counted +# STC [carc](../include/stc/carc.h): Atomic Reference Counted Smart Pointer -**csptr** is a smart pointer that retains shared ownership of an object through a pointer. -Several **csptr** objects may own the same object. The object is destroyed and its memory -deallocated when the last remaining **csptr** owning the object is destroyed with *csptr_X_drop()*; +**carc** is a smart pointer that retains shared ownership of an object through a pointer. +Several **carc** objects may own the same object. The object is destroyed and its memory +deallocated when the last remaining **carc** owning the object is destroyed with *carc_X_drop()*; -The object is destroyed using *csptr_X_drop()*. A **csptr** may also own no objects, in which -case it is called empty. The *csptr_X_cmp()*, *csptr_X_drop()* methods are defined based on -the `i_cmp` and `i_valdrop` macros specified. Use *csptr_X_clone(p)* when sharing ownership of +The object is destroyed using *carc_X_drop()*. A **carc** may also own no objects, in which +case it is called empty. The *carc_X_cmp()*, *carc_X_drop()* methods are defined based on +the `i_cmp` and `i_valdrop` macros specified. Use *carc_X_clone(p)* when sharing ownership of the pointed-to object. -All **csptr** functions can be called by multiple threads on different instances of **csptr** without +All **carc** functions can be called by multiple threads on different instances of **carc** without additional synchronization even if these instances are copies and share ownership of the same object. -**csptr** uses thread-safe atomic reference counting, through the *csptr_X_clone()* and *csptr_X_drop()* methods. +**carc** uses thread-safe atomic reference counting, through the *carc_X_clone()* and *carc_X_drop()* methods. -When declaring a container with shared pointers, define `i_val_bind` as the csptr type, see example. +When declaring a container with shared pointers, define `i_val_bind` as the carc type, see example. -For containers, make sure to pass the result of create functions *csptr_X_new()* **only** to *insert()*, -*push_back()*, and *push()* functions. Use *emplace()* method for sharing existing **csptr**s between -containers or other existing shared pointers, as they internally clone/share the input. +Make sure to pass the result of create functions like *carc_X_from()* **only** to *insert()*, +*push_back()*, and *push()* functions, as it is *moved* into the container. Use *emplace()* +method for sharing existing **carc**s between containers or other existing shared pointers, +as they clone/share the input internally. See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/shared_ptr) for a functional reference, or Rust [std::sync::Arc](https://doc.rust-lang.org/std/sync/struct.Arc.html) / [std::rc::Rc](https://doc.rust-lang.org/std/rc/struct.Rc.html). @@ -29,41 +30,42 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory #define i_drop // destroy value func - defaults to empty destruct #define i_tag // defaults to i_val #define i_opt c_no_atomic // Non-atomic reference counting, like Rust Rc. -#include +#include ``` `X` should be replaced by the value of `i_tag` in all of the following documentation. ## Methods ```c -csptr_X csptr_X_init(); // empty shared pointer -csptr_X csptr_X_new(i_valraw raw); // like csptr_X_from(), but construct owned value from raw. -csptr_X csptr_X_from(i_val val); // create new heap allocated object. Take ownership of val. -csptr_X csptr_X_from_ptr(i_val* p); // create a csptr from raw pointer. Takes ownership of p. - -csptr_X csptr_X_clone(csptr_X other); // return other with increased use count -csptr_X csptr_X_move(csptr_X* self); // transfer ownership to another csptr. -void csptr_X_take(csptr_X* self, csptr_X other); // take ownership of other. -void csptr_X_copy(csptr_X* self, csptr_X other); // copy shared (increase use count) - -void csptr_X_drop(csptr_X* self); // destruct (decrease use count, free at 0) -long csptr_X_use_count(csptr_X ptr); - -void csptr_X_reset(csptr_X* self); -void csptr_X_reset_from(csptr_X* self, i_val val); // assign new csptr with value. Takes ownership of val. - -uint64_t csptr_X_value_hash(const i_val* x, size_t n); // hash value -int csptr_X_value_cmp(const i_val* x, const i_val* y); // compares pointer addresses if 'i_opt c_no_cmp' - // is defined. Otherwise uses 'i_cmp' or default compare. -bool csptr_X_value_eq(const i_val* x, const i_val* y); // cbox_X_value_cmp == 0 +carc_X carc_X_init(); // empty shared pointer +carc_X carc_X_new(i_valraw raw); // like carc_X_from(), but construct owned value from raw. +carc_X carc_X_from(i_val val); // create new heap allocated object. Take ownership of val. +carc_X carc_X_from_ptr(i_val* p); // create a carc from raw pointer. Takes ownership of p. + +carc_X carc_X_clone(carc_X other); // return other with increased use count +carc_X carc_X_move(carc_X* self); // transfer ownership to another carc. +void carc_X_take(carc_X* self, carc_X other); // take ownership of other. +void carc_X_copy(carc_X* self, carc_X other); // copy shared (increase use count) + +void carc_X_drop(carc_X* self); // destruct (decrease use count, free at 0) +long carc_X_use_count(carc_X ptr); + +void carc_X_reset(carc_X* self); +void carc_X_reset_from(carc_X* self, i_val val); // assign new carc with value. Takes ownership of val. + +uint64_t carc_X_value_hash(const i_val* x, size_t n); // hash value +int carc_X_value_cmp(const i_val* x, const i_val* y); // compares pointer addresses if 'i_opt c_no_cmp' + // is defined. Otherwise uses 'i_cmp' or default compare. +bool carc_X_value_eq(const i_val* x, const i_val* y); // cbox_X_value_cmp == 0 ``` ## Types and constants -| Type name | Type definition | Used to represent... | -|:-------------------|:---------------------------------------------------|:------------------------| -| `csptr_null` | `{NULL, NULL}` | Init nullptr const | -| `csptr_X` | `struct { csptr_X_value* get; long* use_count; }` | The csptr type | -| `csptr_X_value` | `i_val` | The csptr element type | +| Type name | Type definition | Used to represent... | +|:------------------|:--------------------------------------------------|:-----------------------| +| `carc_null` | `{NULL, NULL}` | Init nullptr const | +| `carc_X` | `struct { carc_X_value* get; long* use_count; }` | The carc type | +| `carc_X_value` | `i_val` | The carc element type | +| `carc_X_raw` | `i_valraw` | Convertion type | ## Example @@ -83,14 +85,14 @@ bool csptr_X_value_eq(const i_val* x, const i_val* y); // cbox_X_value // no comparison of Maps needed (or available), and // no need for atomic ref. count in single thread: #define i_opt c_no_cmp|c_no_atomic -#include +#include #define i_type Stack -#define i_val_bind Arc // define i_val_bind for csptr / cbox value, not i_val +#define i_val_sptr Arc // define i_val_sptr for carc/cbox value, not i_val or i_val_bind #include #define i_type List -#define i_val_bind Arc // as above +#define i_val_sptr Arc // as above #include int main() @@ -100,28 +102,28 @@ int main() { // POPULATE the stack with shared pointers to Map: Map *map; - map = Stack_push(&stack, Arc_new(Map_init()))->get; + map = Stack_push(&stack, Arc_from(Map_init()))->get; c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, { {"Joey", 1990}, {"Mary", 1995}, {"Joanna", 1992} }); - map = Stack_push(&stack, Arc_new(Map_init()))->get; + map = Stack_push(&stack, Arc_from(Map_init()))->get; c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, { {"Rosanna", 2001}, {"Brad", 1999}, {"Jack", 1980} }); // POPULATE the list: - map = List_push_back(&list, Arc_new(Map_init()))->get; + map = List_push_back(&list, Arc_from(Map_init()))->get; c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, { {"Steve", 1979}, {"Rick", 1974}, {"Tracy", 2003} }); - // Share two Maps from the stack with the list using emplace (clones the csptr): + // Share two Maps from the stack with the list using emplace (clones the carc): List_emplace_back(&list, stack.data[0]); List_emplace_back(&list, stack.data[1]); // Clone (deep copy) a Map from the stack to the list // List will contain two shared and two unshared maps. - map = List_push_back(&list, Arc_new(Map_clone(*stack.data[1].get)))->get; + map = List_push_back(&list, Arc_from(Map_clone(*stack.data[1].get)))->get; // Add one more element to the cloned map: Map_emplace_or_assign(map, "CLONED", 2021); -- cgit v1.2.3