INPUT += ../../include/simgrid/semaphore.h
INPUT += ../../include/simgrid/vm.h
INPUT += ../../include/simgrid/zone.h
+INPUT += ../../include/xbt/dynar.h
+INPUT += ../../src/xbt/dynar.cpp
INPUT += ../../include/xbt/signal.hpp
INPUT += ../../src/msg/
INPUT += ../../src/plugins/
You should obviously install the ``boost-context`` library on your
machine, for example with ``apt``.
+.. _deprecation_policy:
+
Version numbering and deprecation
---------------------------------
You can even specify a compile-time threshold that will completely remove every logging below the specified priority. Passing ``-DNDEBUG`` to cmake disables every logging of
priority below INFO while ``-DNLOG`` removes any logging at compile time. Note that using this feature may hinder the stability of SimGrid, as we consider the logs to be fast
enough to not thoughtfully test the case where they are removed at compile time.
+
+Dynamic arrays
+**************
+
+As SimGrid used to be written in pure C, it used to rely on custom data containers such as dynamic arrays and dictionnaries. Nowadays, the standard library of
+C++ is used internally, but some part of the interface still rely on the old containers, that are thus still available.
+
+.. warning::
+
+ You should probably not start a new project using these data structures, as we will :ref:`deprecate them from SimGrid <deprecation_policy>`
+ as soon as possible. Better implementations exist out there anyway, in particular if you're not writting pure C code.
+
+.. doxygentypedef:: xbt_dynar_t
+.. doxygentypedef:: const_xbt_dynar_t
+
+Creation and destruction
+========================
+
+.. doxygenfunction:: xbt_dynar_new
+.. doxygenfunction:: xbt_dynar_free
+.. doxygenfunction:: xbt_dynar_free_container
+.. doxygenfunction:: xbt_dynar_shrink
+
+Dynars as regular arrays
+========================
+
+.. doxygenfunction:: xbt_dynar_get_cpy
+.. doxygenfunction:: xbt_dynar_insert_at
+.. doxygenfunction:: xbt_dynar_remove_at
+.. doxygenfunction:: xbt_dynar_member
+.. doxygenfunction:: xbt_dynar_sort
+
+Dynar size
+==========
+
+.. doxygenfunction:: xbt_dynar_is_empty
+.. doxygenfunction:: xbt_dynar_length
+.. doxygenfunction:: xbt_dynar_reset
+
+Perl-like interface
+===================
+
+.. doxygenfunction:: xbt_dynar_push
+.. doxygenfunction:: xbt_dynar_pop
+.. doxygenfunction:: xbt_dynar_unshift
+.. doxygenfunction:: xbt_dynar_shift
+.. doxygenfunction:: xbt_dynar_map
+
+Direct content manipulation
+===========================
+
+Those functions do not retrieve the content, but only their address.
+
+.. doxygenfunction:: xbt_dynar_set_at_ptr
+.. doxygenfunction:: xbt_dynar_get_ptr
+.. doxygenfunction:: xbt_dynar_insert_at_ptr
+.. doxygenfunction:: xbt_dynar_push_ptr
+.. doxygenfunction:: xbt_dynar_pop_ptr
+
+Dynars of scalars
+=================
+
+While the other functions use a memcpy to retrieve the content into the user provided area, those ones use a
+regular affectation. It only works for scalar values, but should be a little faster.
+
+.. doxygendefine:: xbt_dynar_get_as
+.. doxygendefine:: xbt_dynar_set_as
+
+.. doxygendefine:: xbt_dynar_getlast_as
+.. doxygendefine:: xbt_dynar_getfirst_as
+.. doxygendefine:: xbt_dynar_push_as
+.. doxygendefine:: xbt_dynar_pop_as
+
+Iterating over Dynars
+=====================
+
+.. doxygendefine:: xbt_dynar_foreach
+
+Example with scalar values
+==========================
+
+.. code-block:: c
+
+ xbt_dynar_t d = xbt_dynar_new(sizeof(int), nullptr);
+
+ /* 1. Populate the dynar */
+ xbt_dynar_t d = xbt_dynar_new(sizeof(int), nullptr);
+ for (int cpt = 0; cpt < NB_ELEM; cpt++) {
+ xbt_dynar_push_as(d, int, cpt); /* This is faster (and possible only with scalars) */
+ /* xbt_dynar_push(d,&cpt); This would also work */
+ xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
+ }
+
+ /* 2. Traverse manually the dynar */
+ for (cursor = 0; cursor < NB_ELEM; cursor++) {
+ int* iptr = (int*)xbt_dynar_get_ptr(d, cursor);
+ /* 1. Populate further the dynar */
+ for (int cpt = 0; cpt < NB_ELEM; cpt++) {
+ xbt_dynar_insert_at(d, cpt, &cpt);
+ xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
+ }
+
+ /* 3. Traverse the dynar */
+ int cpt;
+ xbt_dynar_foreach(d, cursor, cpt) {
+ xbt_test_assert(cursor == (unsigned int) cpt, "The retrieved value is not the same than the injected one (%u!=%d)", cursor, cpt);
+ }
+
+ /* 4. Reset the values */
+ for (int i = 0; i < NB_ELEM; i++)
+ *(int*)xbt_dynar_get_ptr(d, i) = i;
+
+ /* 5. Shift all the values */
+ for (int i = 0; i < NB_ELEM; i++) {
+ int val;
+ xbt_dynar_shift(d, &val);
+ }
+ // the dynar is empty after shifting all values
+
+ /* 5. Free the resources */
+ xbt_dynar_free(&d);
+
+Example with pointed values
+===========================
+
+.. code-block:: c
+
+ xbt_dynar_t d = xbt_dynar_new(sizeof(char*), &xbt_free_ref);
+
+ /// Push/shift example
+ for (int i = 0; i < NB_ELEM; i++) {
+ char * val = xbt_strdup("hello");
+ xbt_dynar_push(d, &val);
+ }
+ for (int i = 0; i < NB_ELEM; i++) {
+ char *val;
+ xbt_dynar_shift(d, &val);
+ REQUIRE("hello" == val);
+ xbt_free(val);
+ }
+ xbt_dynar_free(&d);
+
+ /// Unshift, traverse and pop example
+ d = xbt_dynar_new(sizeof(char**), &xbt_free_ref);
+ for (int i = 0; i < NB_ELEM; i++) {
+ std::string val = std::to_string(i);
+ s1 = xbt_strdup(val.c_str());
+ xbt_dynar_unshift(d, &s1);
+ }
+ /* 2. Traverse the dynar with the macro */
+ xbt_dynar_foreach (d, iter, s1) {
+ std::string val = std::to_string(NB_ELEM - iter - 1);
+ REQUIRE(s1 == val); // The retrieved value is not the same than the injected one
+ }
+ /* 3. Traverse the dynar with the macro */
+ for (int i = 0; i < NB_ELEM; i++) {
+ std::string val = std::to_string(i);
+ xbt_dynar_pop(d, &s2);
+ REQUIRE(s2 == val); // The retrieved value is not the same than the injected one
+ xbt_free(s2);
+ }
+ /* 4. Free the resources */
+ xbt_dynar_free(&d);
('cpp:identifier', 'this_actor'),
('cpp:identifier', 'uint64_t'),
('cpp:identifier', 'xbt'),
+ ('cpp:identifier', 'xbt_dynar_s'),
('cpp:identifier', 'xbt::Extendable<Actor>'),
('cpp:identifier', 'xbt::Extendable<Disk>'),
('cpp:identifier', 'xbt::Extendable<File>'),
SG_BEGIN_DECL
-/** @addtogroup XBT_dynar
- * @brief DynArr are dynamically sized vector which may contain any type of variables.
+/** @brief Dynar data type (opaque type)
*
- * These are the SimGrid version of the dynamically size arrays, which all C programmer recode one day or another.
- *
- * For performance concerns, the content of DynArr must be homogeneous (in contrary to dictionaries -- see the
- * @ref XBT_dict section). You thus have to provide the function which will be used to free the content at
+ * These are the SimGrid version of the DYNamically sized ARays, which all C programmer recode one day or another.
+ * For performance concerns, the content of dynars must be homogeneous (in contrary to @ref xbt_dict_t).
+ * You thus have to provide the function which will be used to free the content at
* structure creation (of type void_f_pvoid_t).
- *
- * @deprecated If you are using C++, you might want to use `std::vector` instead.
- *
- * @section XBT_dynar_exscal Example with scalar
- * @dontinclude dynar.cpp
- *
- * @skip Vars_decl
- * @skip dyn
- * @until iptr
- * @skip Populate_ints
- * @skip dyn
- * @until end_of_traversal
- * @skip shifting
- * @skip val
- * @until xbt_dynar_free
- *
- * @section XBT_dynar_exptr Example with pointed data
- *
- * @skip test_dynar_string
- * @skip dynar_t
- * @until s2
- * @skip Populate_str
- * @skip dyn
- * @until }
- * @skip macro
- * @until dynar_free
- * @skip end_of_doxygen
- * @until }
- *
- * Note that if you use dynars to store pointed data, xbt_dynar_member() won't be for you. Instead of comparing your
- * pointed elements, it compares the pointer to them.
*/
-/** @defgroup XBT_dynar_cons Dynar constructor and destructor
- * @ingroup XBT_dynar
- *
- * @{
- */
-/** @brief Dynar data type (opaque type) */
typedef struct xbt_dynar_s *xbt_dynar_t;
+/** constant dynar */
typedef const struct xbt_dynar_s* const_xbt_dynar_t;
+/* @warning DO NOT USE THIS STRUCTURE DIRECTLY! Use the public interface, even if it's public for sake of inlining */
+typedef struct xbt_dynar_s {
+ unsigned long size;
+ unsigned long used;
+ unsigned long elmsize;
+ void* data;
+ void_f_pvoid_t free_f;
+} s_xbt_dynar_t;
XBT_PUBLIC xbt_dynar_t xbt_dynar_new(const unsigned long elm_size, void_f_pvoid_t free_f);
XBT_PUBLIC void xbt_dynar_free(xbt_dynar_t* dynar);
XBT_PUBLIC void xbt_dynar_free_container(xbt_dynar_t* dynar);
XBT_PUBLIC void xbt_dynar_shrink(xbt_dynar_t dynar, int empty_slots);
-/** @} */
-/** @defgroup XBT_dynar_array Dynar as a regular array
- * @ingroup XBT_dynar
- *
- * @{
- */
-
+/* Dynar as a regular array */
XBT_PUBLIC void xbt_dynar_get_cpy(const_xbt_dynar_t dynar, unsigned long idx, void* dst);
XBT_PUBLIC void xbt_dynar_insert_at(xbt_dynar_t dynar, int idx, const void* src);
XBT_PUBLIC void xbt_dynar_sort(const_xbt_dynar_t dynar, int_f_cpvoid_cpvoid_t compar_fn);
XBT_ATTRIB_DEPRECATED_v331("This function will be removed") XBT_PUBLIC void* xbt_dynar_to_array(xbt_dynar_t dynar);
-/** @} */
-/** @defgroup XBT_dynar_misc Dynar miscellaneous functions
- * @ingroup XBT_dynar
- *
- * @{
- */
-
+/* Dynar size */
+XBT_PUBLIC void xbt_dynar_reset(xbt_dynar_t dynar);
XBT_PUBLIC unsigned long xbt_dynar_length(const_xbt_dynar_t dynar);
XBT_PUBLIC int xbt_dynar_is_empty(const_xbt_dynar_t dynar);
-XBT_PUBLIC void xbt_dynar_reset(xbt_dynar_t dynar);
-
-/** @} */
-/** @defgroup XBT_dynar_perl Perl-like use of dynars
- * @ingroup XBT_dynar
- *
- * @{
- */
+/* Perl-like interface */
XBT_PUBLIC void xbt_dynar_push(xbt_dynar_t dynar, const void* src);
XBT_PUBLIC void xbt_dynar_pop(xbt_dynar_t dynar, void* dst);
XBT_PUBLIC void xbt_dynar_unshift(xbt_dynar_t dynar, const void* src);
XBT_PUBLIC void xbt_dynar_shift(xbt_dynar_t dynar, void* dst);
XBT_PUBLIC void xbt_dynar_map(const_xbt_dynar_t dynar, void_f_pvoid_t op);
-/** @} */
-/** @defgroup XBT_dynar_ctn Direct manipulation to the dynars content
- * @ingroup XBT_dynar
- *
- * Those functions do not retrieve the content, but only their address.
- *
- * @{
- */
-
+/* Direct content manipulation*/
XBT_PUBLIC void* xbt_dynar_set_at_ptr(const xbt_dynar_t dynar, unsigned long idx);
XBT_PUBLIC void* xbt_dynar_get_ptr(const_xbt_dynar_t dynar, unsigned long idx);
XBT_PUBLIC void* xbt_dynar_insert_at_ptr(xbt_dynar_t dynar, int idx);
XBT_PUBLIC void* xbt_dynar_push_ptr(xbt_dynar_t dynar);
XBT_PUBLIC void* xbt_dynar_pop_ptr(xbt_dynar_t dynar);
-/** @} */
-/** @defgroup XBT_dynar_speed Speed optimized access to dynars of scalars
- * @ingroup XBT_dynar
- *
- * While the other functions use a memcpy to retrieve the content into the user provided area, those ones use a
- * regular affectation. It only works for scalar values, but should be a little faster.
- *
- * @{
- */
-
- /** @brief Quick retrieval of scalar content
- * @hideinitializer */
+/* Dynars of scalar */
+/** @brief Quick retrieval of scalar content
+ * @hideinitializer */
# define xbt_dynar_get_as(dynar,idx,type) \
(*(type*)xbt_dynar_get_ptr((dynar),(idx)))
/** @brief Quick setting of scalar content
# define xbt_dynar_pop_as(dynar,type) \
(*(type*)xbt_dynar_pop_ptr(dynar))
-/** @} */
-/** @defgroup XBT_dynar_cursor Cursors on dynar
- * @ingroup XBT_dynar
- *
- * Cursors are used to iterate over the structure. Never add elements to the DynArr during the traversal.
- *
- * @{
- */
-
-/*
- * @warning DO NOT USE THIS STRUCTURE DIRECTLY! Instead, use the public interface:
- * This was made public to allow:
- * - the inlining of the foreach elements
- * - sending such beasts over the network
- *
- * @see xbt_dynar_length()
- */
-typedef struct xbt_dynar_s {
- unsigned long size;
- unsigned long used;
- unsigned long elmsize;
- void *data;
- void_f_pvoid_t free_f;
-} s_xbt_dynar_t;
-
+/* Iterating over dynars */
static inline int _xbt_dynar_cursor_get(const_xbt_dynar_t dynar, unsigned int idx, void* dst)
{
if (!dynar) /* iterating over a NULL dynar is a no-op */
/** @brief Iterates over the whole dynar.
*
* @param _dynar what to iterate over
- * @param _cursor an integer used as cursor
- * @param _data
+ * @param _cursor an unsigned integer used as cursor
* @hideinitializer
*
* Here is an example of usage:
* @code
xbt_dynar_t dyn;
unsigned int cpt;
-string *str;
+char* str;
xbt_dynar_foreach (dyn,cpt,str) {
printf("Seen %s\n",str);
}
@endcode
*
* Note that underneath, that's a simple for loop with no real black magic involved. It's perfectly safe to interrupt
- * a foreach with a break or a return statement.
+ * a foreach with a break or a return statement, but inserting or removing elements during the traversal is probably a
+ * bad idea (even if you can fix side effects by manually changing the counter).
*/
#define xbt_dynar_foreach(_dynar, _cursor, _data) \
for ((_cursor) = 0; _xbt_dynar_cursor_get((_dynar), (_cursor), &(_data)); (_cursor)++)
-
-/** @} */
SG_END_DECL
#endif /* XBT_DYNAR_H */
memcpy(dst, elm, dynar->elmsize);
}
-/** @brief Constructor
+/**
+ * Creates a new dynar. If a @c free_f is provided, the elements have to be pointer of pointer. That is to say that
+ * dynars can contain either base types (int, char, double, etc) or pointer of pointers (struct **).
*
* @param elmsize size of each element in the dynar
* @param free_f function to call each time we want to get rid of an element (or nullptr if nothing to do).
- *
- * Creates a new dynar. If a free_func is provided, the elements have to be pointer of pointer. That is to say that
- * dynars can contain either base types (int, char, double, etc) or pointer of pointers (struct **).
*/
xbt_dynar_t xbt_dynar_new(const unsigned long elmsize, void_f_pvoid_t free_f)
{
return dynar;
}
-/** @brief Destructor of the structure not touching to the content
+/** Destructor of the structure leaving the content unmodified. Ie, the array is freed, but the content is not touched
+ * (the @a free_f function is not used).
*
* @param dynar poor victim
- *
- * kilkil a dynar BUT NOT its content. Ie, the array is freed, but the content is not touched (the @a free_f function
- * is not used)
*/
void xbt_dynar_free_container(xbt_dynar_t* dynar)
{
}
}
-/** @brief Frees the content and set the size to 0
- *
- * @param dynar who to squeeze
- */
+/** @brief Frees the content and set the size to 0 */
void xbt_dynar_reset(xbt_dynar_t dynar)
{
_sanity_check_dynar(dynar);
}
/**
- * @brief Shrink the dynar by removing empty slots at the end of the internal array
- * @param dynar a dynar
- * @param empty_slots_wanted number of empty slots you want to keep at the end of the internal array for further
- * insertions
+ * Shrinks (reduces) the dynar by removing empty slots in the internal storage to save memory.
+ * If @c empty_slots_wanted is not zero, this operation preserves that amount of empty slot, for fast future additions.
+ * Note that if @c empty_slots_wanted is large enough, the internal array is expanded instead of shrunk.
*
- * Reduces the internal array size of the dynar to the number of elements plus @a empty_slots_wanted.
- * After removing elements from the dynar, you can call this function to make the dynar use less memory.
- * Set @a empty_slots_wanted to zero to reduce the dynar internal array as much as possible.
- * Note that if @a empty_slots_wanted is greater than the array size, the internal array is expanded instead of shrunk.
+ * @param dynar a dynar
+ * @param empty_slots_wanted number of empty slots elements that can be inserted the internal storage without resizing it
*/
void xbt_dynar_shrink(xbt_dynar_t dynar, int empty_slots_wanted)
{
_xbt_dynar_resize(dynar, dynar->used + empty_slots_wanted);
}
-/** @brief Destructor
- *
- * @param dynar poor victim
- *
- * kilkil a dynar and its content
- */
+/** @brief Destructor: kilkil a dynar and its content. */
void xbt_dynar_free(xbt_dynar_t* dynar)
{
if (dynar && *dynar) {
}
}
-/** @brief Count of dynar's elements
- *
- * @param dynar the dynar we want to measure
- */
+/** @brief Count of dynar's elements */
unsigned long xbt_dynar_length(const_xbt_dynar_t dynar)
{
return (dynar ? dynar->used : 0UL);
}
-/**@brief check if a dynar is empty
- *
- *@param dynar the dynat we want to check
- */
+/**@brief check if a dynar is empty */
int xbt_dynar_is_empty(const_xbt_dynar_t dynar)
{
return (xbt_dynar_length(dynar) == 0);
/** @brief Retrieve a pointer to the Nth element of a dynar.
*
- * @param dynar information dealer
- * @param idx index of the slot we want to retrieve
- * @return the @a idx-th element of @a dynar.
- *
- * @warning The returned value is the actual content of the dynar.
+ * Note that the returned value is the actual content of the dynar.
* Make a copy before fooling with it.
*/
void* xbt_dynar_get_ptr(const_xbt_dynar_t dynar, unsigned long idx)
memcpy(xbt_dynar_insert_at_ptr(dynar, idx), src, dynar->elmsize);
}
-/** @brief Remove the Nth dynar's element, sliding the previous values to the left
+/** @brief Remove the Nth element, sliding other values to the left
*
* Get the Nth element of a dynar, removing it from the dynar and moving all subsequent values to one position left in
* the dynar.
/** @brief Returns a boolean indicating whether the element is part of the dynar
*
* Beware that if your dynar contains pointed values (such as strings) instead of scalar, this function is probably not
- * what you want.
+ * what you want. It would compare the pointer values, not the pointed elements.
*/
int xbt_dynar_member(const_xbt_dynar_t dynar, const void* elem)
{
* a comparison function. Here is a quick example if you have integers in your dynar:
*
* @verbatim
- * int cmpfunc (const void * a, const void * b) {
- * int intA = *(int*)a;
- * int intB = *(int*)b;
- * return intA - intB;
- * }
- * @endverbatim
+ int cmpfunc (const void * a, const void * b) {
+ int intA = *(int*)a;
+ int intB = *(int*)b;
+ return intA - intB;
+ }
+ @endverbatim
*
- * and now to sort a dynar of MSG hosts depending on their speed:
+ * And now, a function to sort a dynar of MSG hosts depending on their speed:
* @verbatim
- * int cmpfunc(const MSG_host_t a, const MSG_host_t b) {
- * MSG_host_t hostA = *(MSG_host_t*)a;
- * MSG_host_t hostB = *(MSG_host_t*)b;
- * return MSG_host_get_speed(hostA) - MSG_host_get_speed(hostB);
- * }
- * @endverbatim
+ int cmpfunc(const MSG_host_t a, const MSG_host_t b) {
+ MSG_host_t hostA = *(MSG_host_t*)a;
+ MSG_host_t hostB = *(MSG_host_t*)b;
+ return MSG_host_get_speed(hostA) - MSG_host_get_speed(hostB);
+ }
+ @endverbatim
*
* @param dynar the dynar to sort
* @param compar_fn comparison function of type (int (compar_fn*) (const void*) (const void*)).
{
SECTION("Dynars of integers")
{
- /* Vars_decl [doxygen cruft] */
int cpt;
unsigned int cursor;
/* in your code is naturally the way to go outside a regression test */
INFO("==== Push " << NB_ELEM << " int, set them again 3 times, traverse them, shift them");
- /* Populate_ints [doxygen cruft] */
/* 1. Populate the dynar */
d = xbt_dynar_new(sizeof(int), nullptr);
for (int i = 0; i < NB_ELEM; i++) {
