diff options
Diffstat (limited to 'docs/csptr_api.md')
| -rw-r--r-- | docs/csptr_api.md | 94 |
1 files changed, 47 insertions, 47 deletions
diff --git a/docs/csptr_api.md b/docs/csptr_api.md index 640f5cf1..5cbe746f 100644 --- a/docs/csptr_api.md +++ b/docs/csptr_api.md @@ -1,19 +1,19 @@ -# STC [csptr](../include/stc/csptr.h): Shared Pointers +# STC [csptr](../include/stc/csptr.h): Atomic Reference Counted **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_del()*; +deallocated when the last remaining **csptr** owning the object is destroyed with *csptr_X_drop()*; -The object is destroyed using *csptr_X_del()*. A **csptr** may also own no objects, in which -case it is called empty. The *csptr_X_compare()*, *csptr_X_del()* methods are defined based on -the `i_cmp` and `i_valdel` macros specified. Use *csptr_X_clone(p)* when sharing ownership of +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 pointed-to object. All **csptr** functions can be called by multiple threads on different instances of **csptr** 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_del()* methods. +**csptr** uses thread-safe atomic reference counting, through the *csptr_X_clone()* and *csptr_X_drop()* methods. -When declaring a container with shared pointers, define `i_val_ref` as the csptr type, see example. +When declaring a container with shared pointers, define `i_val_bind` as the csptr 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 @@ -26,7 +26,7 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory ```c #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_del // destroy value func - defaults to empty destruct +#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> @@ -35,34 +35,34 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory ## Methods ```c -csptr_X csptr_X_init(); // empty shared pointer -csptr_X csptr_X_new(i_val val); // create new heap allocated object. Take ownership of val. -csptr_X csptr_X_from(i_rawval raw); // like csptr_X_new(), but construct owned value from raw. -csptr_X csptr_X_with(i_val* p); // create a csptr from raw pointer. Takes ownership of p. +csptr_X csptr_X_init(); // empty shared pointer +csptr_X csptr_X_new(i_val val); // create new heap allocated object. Take ownership of val. +csptr_X csptr_X_from(i_valraw raw); // like csptr_X_new(), but construct owned value from raw. +csptr_X csptr_X_with(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) +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_del(csptr_X* self); // destruct (decrease use count, free at 0) +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_new(csptr_X* self, i_val val); // assign new csptr with value. Takes ownership of val. -void csptr_X_reset_from(csptr_X* self, i_rawval raw); // make and assign new csptr from raw value. +void csptr_X_reset_from(csptr_X* self, i_valraw raw); // make and assign new csptr from raw value. void csptr_X_reset_with(csptr_X* self, i_val* p); // create csptr with pointer p. Takes ownership of p. -int csptr_X_compare(const csptr_X* x, const csptr_X* y); // compares pointer addresses if 'i_opt c_no_compare' - // is defined. Otherwise uses 'i_cmp' or default compare. +int csptr_X_cmp(const csptr_X* x, const csptr_X* y); // compares pointer addresses if 'i_opt c_no_cmp' + // is defined. Otherwise uses 'i_cmp' or default compare. ``` ## 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 | +| 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 | ## Example @@ -73,24 +73,24 @@ int csptr_X_compare(const csptr_X* x, const csptr_X* y); // compares poi #define i_type Map #define i_key_str // strings #define i_val int -#define i_keydel(p) (printf("del name: %s\n", (p)->str), cstr_del(p)) +#define i_keydrop(p) (printf("drop name: %s\n", (p)->str), cstr_drop(p)) #include <stc/csmap.h> #define i_type Arc // (atomic) ref. counted type #define i_val Map #define i_from Map_clone -#define i_del(p) (printf("del Arc:\n"), Map_del(p)) +#define i_drop(p) (printf("drop Arc:\n"), Map_drop(p)) // no comparison of Maps needed (or available), and // no need for atomic ref. count in single thread: -#define i_opt c_no_compare|c_no_atomic +#define i_opt c_no_cmp|c_no_atomic #include <stc/csptr.h> #define i_type Stack -#define i_val_ref Arc // define i_val_ref for csptr / cbox value, not i_val +#define i_val_bind Arc // define i_val_bind for csptr / cbox value, not i_val #include <stc/cstack.h> #define i_type List -#define i_val_ref Arc // as above +#define i_val_bind Arc // as above #include <stc/clist.h> int main() @@ -155,22 +155,22 @@ LIST Joanna:1992 Joey:1990 Mary:1995 Brad:1999 Jack:1980 Rosanna:2001 SHARED:2021 Brad:1999 CLONED:2021 Jack:1980 Rosanna:2001 -del Arc: -del name: Rick -del name: Tracy -del name: Steve -del Arc: -del name: CLONED -del name: Brad -del name: Rosanna -del name: Jack -del Arc: -del name: Brad -del name: SHARED -del name: Rosanna -del name: Jack -del Arc: -del name: Joanna -del name: Mary -del name: Joey +drop Arc: +drop name: Rick +drop name: Tracy +drop name: Steve +drop Arc: +drop name: CLONED +drop name: Brad +drop name: Rosanna +drop name: Jack +drop Arc: +drop name: Brad +drop name: SHARED +drop name: Rosanna +drop name: Jack +drop Arc: +drop name: Joanna +drop name: Mary +drop name: Joey ``` |