diff options
Diffstat (limited to 'docs/csptr_api.md')
| -rw-r--r-- | docs/csptr_api.md | 96 |
1 files changed, 49 insertions, 47 deletions
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 <stc/csptr.h> +#include <stc/carc.h> ``` `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 <stc/csptr.h> +#include <stc/carc.h> #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 <stc/cstack.h> #define i_type List -#define i_val_bind Arc // as above +#define i_val_sptr Arc // as above #include <stc/clist.h> 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); |