Remove obsolete m-i-shared.h header
This commit is contained in:
Patrick Pelissier committed
1 parent
7e8cb07a6c
commit
25dcdeed69
4 files changed
-588
No files matched your search
@@ -197,7 +197,6 @@ Finally, headers for compatibility with non C11 compilers:
|
||||
|
||||
The following headers are obsolete and will be removed in the next major release:
|
||||
* [m-concurrent.h](#m-concurrent): header for transforming a container into a concurrent container (thread safe),
|
||||
* [m-i-shared.h](#m-i-shared): header for creating intrusive shared pointer of generic type (Thread Safe).
|
||||
* [m-mempool.h](#m-mempool): header for creating specialized & fast memory allocator,
|
||||
|
||||
Each containers define their iterators (if it is meaningful).
|
||||
@@ -5085,184 +5084,6 @@ Create a new shared object initialized with its `INIT_SET` operator on the given
|
||||
This method is created only if the `INIT_SET` operator is defined.
|
||||
|
||||
|
||||
_________________
|
||||
|
||||
### M-I-SHARED
|
||||
|
||||
> [!NOTE]
|
||||
> This header is obsolete: M-SHARED-PTR should be used instead.
|
||||
|
||||
This header is for creating intrusive shared pointer.
|
||||
|
||||
#### `ISHARED_PTR_INTERFACE(name, type)`
|
||||
|
||||
Extend the definition of the structure of an object of type `type` by adding the
|
||||
necessary interface to handle it as a shared pointer named `name`.
|
||||
It shall be put within the structure definition of the object (See example).
|
||||
|
||||
#### `ISHARED_PTR_STATIC_INIT(name, type)`
|
||||
|
||||
Provide the static initialization value of an object defined with a
|
||||
`ISHARED_PTR_INTERFACE` extra fields. It shall be used only for global
|
||||
variables with the _init_once function.
|
||||
|
||||
Usage (provided that the interface is used as the first element of the structure):
|
||||
|
||||
```C
|
||||
struct mystruct variable = { ISHARED_PTR_STATIC_INIT(ishared_double, struct mystruct) };
|
||||
```
|
||||
|
||||
#### `ISHARED_PTR_STATIC_DESIGNATED_INIT(name, type)`
|
||||
|
||||
Provide the static initialization value of an object defined with a
|
||||
`ISHARED_PTR_INTERFACE` extra fields. It shall be used only for global
|
||||
variables with the _init_once function.
|
||||
|
||||
It uses designated initializers to set the right fields.
|
||||
|
||||
Usage:
|
||||
|
||||
```C
|
||||
struct mystruct variable = {ISHARED_PTR_STATIC_DESIGNATED_INIT(ishared_double, struct mystruct) };
|
||||
```
|
||||
|
||||
#### `ISHARED_PTR_DEF(name, type[, oplist])`
|
||||
#### `ISHARED_PTR_DEF_AS(name, name_t, type[, oplist])`
|
||||
|
||||
Define the associated methods to handle the shared pointer named `name`
|
||||
as `static inline` functions.
|
||||
A shared pointer is a mechanism to keep tracks of all `users` of an object
|
||||
and performs an automatic destruction of the object whenever all users release
|
||||
their need on this object.
|
||||
|
||||
The destruction of the object is thread safe and occurs when the last user
|
||||
of the object releases it. The destruction of the object implies:
|
||||
|
||||
* calling the `CLEAR` operator to clear the object,
|
||||
* calling the `DEL` operator to release the memory used by the object
|
||||
(if the method has not been disabled).
|
||||
|
||||
The object oplist is expected to have the following operators (`CLEAR` and `DEL`),
|
||||
otherwise default methods are used. If there is no given oplist, the default
|
||||
operators are also used. The created methods will use the operators to init, set
|
||||
and clear the contained object.
|
||||
|
||||
There are designed to work with buffers with policy `BUFFER_PUSH_INIT_POP_MOVE`
|
||||
to send a shared pointer across multiple threads.
|
||||
|
||||
It is recommended to use the intrusive shared pointer over the standard one if
|
||||
possible. They are faster and cleaner.
|
||||
|
||||
The default is to use heap allocated entities, which are allocated by `NEW` and
|
||||
freed by `DEL`.
|
||||
|
||||
It can be used for statically allocated entities. However, in this case,
|
||||
you shall disable the operator `NEW` and `DEL` when expanding the oplist
|
||||
so that the destruction doesn't try to free the objects, like this:
|
||||
|
||||
```C
|
||||
(NEW(0), DEL(0))
|
||||
```
|
||||
|
||||
`NEW` and `DEL` operators shall be either both defined, or both disabled.
|
||||
|
||||
`ISHARED_PTR_DEF_AS` is the same as `ISHARED_PTR_DEF` except the name of the type `name_t`
|
||||
is provided.
|
||||
|
||||
Example (dynamic):
|
||||
|
||||
```C
|
||||
typedef struct mystruct_s {
|
||||
ISHARED_PTR_INTERFACE(ishared_mystruct, struct mystruct_s);
|
||||
char *message;
|
||||
} mystruct_t;
|
||||
|
||||
static inline void mystruct_init(mystruct_t *p) { p->message = NULL; }
|
||||
static inline void mystruct_clear(mystruct_t *p) { free(p->message); }
|
||||
|
||||
ISHARED_PTR_DEF(ishared_mystruct, mystruct_t, (INIT(mystruct_init), CLEAR(mystruct_clear M_IPTR)))
|
||||
|
||||
void f(void) {
|
||||
mystruct_t *p = ishared_mystruct_init_new();
|
||||
p->message = strdup ("Hello");
|
||||
buffer_mystruct_push(g_buff1, p);
|
||||
buffer_mystruct_push(g_buff2, p);
|
||||
ishared_mystruct_clear(p);
|
||||
}
|
||||
```
|
||||
|
||||
#### Created types
|
||||
|
||||
The following types are automatically defined by the previous definition macro if not provided by the user:
|
||||
|
||||
##### `name_t`
|
||||
|
||||
It will define name_t as a pointer to shared counted object.
|
||||
This is a synonymous to a pointer to the object.
|
||||
|
||||
#### Specialized methods
|
||||
|
||||
The following specialized methods are automatically created by the previous definition macro:
|
||||
|
||||
##### `name_t name_init(type *object)`
|
||||
|
||||
Return a shared pointer to `object` which owns `object`.
|
||||
It initializes the private fields of `object` handling the shared pointer,
|
||||
returning the same pointer to the object from a value point of view,
|
||||
but with the shared pointer field initialized.
|
||||
|
||||
As a consequence, the shared pointer part of `object` shall not have been initialized yet.
|
||||
The other part of `object` may or may not be initialized before calling this method.
|
||||
|
||||
##### `name_t name_init_set(name_t shared)`
|
||||
|
||||
Return a new shared pointer to the same object than the one pointed by `shared`,
|
||||
incrementing the ownership of the object.
|
||||
This function is thread safe.
|
||||
|
||||
##### `name_t name_init_new(void)`
|
||||
|
||||
Allocate a new object, initialize it and return an initialized shared pointer to it.
|
||||
The used allocation function is the `NEW` operator.
|
||||
|
||||
This method is only created if the `INIT` and `NEW` methods are provided and not disabled.
|
||||
|
||||
##### `name_t name_init_once(type *object)`
|
||||
|
||||
Initialize the new object `object` and return an initialized shared pointer to it.
|
||||
The `INIT` operator of `object` is ensured to be called only once,
|
||||
even if multiple threads try to initialize it at the same time.
|
||||
Once the object is fully cleared, the initialization function may occur once again.
|
||||
|
||||
`object` shall be a global variable initialized with the
|
||||
`ISHARED_PTR_STATIC_INIT` macro.
|
||||
|
||||
This method is only created if the `INIT` and `NEW` methods are provided and not disabled.
|
||||
|
||||
##### `void name_clear(name_t shared)`
|
||||
|
||||
Clear the `shared` pointer, releasing ownership of the object
|
||||
and destroying the shared object if no longer
|
||||
any other `shared` pointers own it.
|
||||
This function is thread safe.
|
||||
|
||||
##### `void name_clear_ptr(name_t *shared)`
|
||||
|
||||
Clear the shared pointer `*shared`, releasing ownership of the object
|
||||
and destroying the shared object if no longer
|
||||
any other `shared` pointers own it.
|
||||
This function is thread safe.
|
||||
Afterwards, `*shared` is set to NULL.
|
||||
|
||||
##### `void name_set(name_t *shared1, name_t shared2)`
|
||||
|
||||
Update the shared pointer `*shared1` to point to the same object than
|
||||
the shared pointer `shared2`.
|
||||
Destroy the shared object pointed by `*shared1` if no longer any other shared
|
||||
pointers own it, set the shared pointer `shared` to the same object
|
||||
than the one pointed by `src`.
|
||||
This function is thread safe.
|
||||
|
||||
_________________
|
||||
|
||||
### M-I-LIST
|
||||
|
||||
Reference in new issue
Block a user