core docs looking good

Author: ConorWilliams

CMakeLists.txt

@@ -40,10 +40,10 @@ target_compile_features(libfork_libfork INTERFACE cxx_std_23)
 
 # ---- Compiler options ----- #
 
-option(LF_FIBRE_STACK_SIZE "The size of the fibre stack (in multiples 4kb pages)" OFF)
+option(LF_FIBRE_INIT_SIZE "The initial size (bytes) of a fibre's stack (default 4 KiB)" OFF)
 
-if(LF_FIBRE_STACK_SIZE)
-  target_compile_definitions(libfork_libfork INTERFACE LF_FIBRE_STACK_SIZE=${LF_FIBRE_STACK_SIZE})
+if(LF_FIBRE_INIT_SIZE)
+  target_compile_definitions(libfork_libfork INTERFACE LF_FIBRE_INIT_SIZE=${LF_FIBRE_INIT_SIZE})
 endif()
 
 # If this is off then libfork will store a pointer to avoid any UB, enable only as an optimization

TODO.md

@@ -2,8 +2,6 @@
 
 - Check HWLOC numa detection is up to par
 
-- Make LF_FIBER_STACK_SIZE set init fibre size instead of current
-
 - Benchmarks working, run benchmarks on CSD3 with mimalloc
 
 - Fix github actions

docs/api/core.gen.rst

@@ -1,38 +1,41 @@
 Core API
 ===================
 
-The ``core`` namespace contains the basic building blocks of the library.  
-To include all of ``core`` use ``#include <libfork/core.hpp>``.
+The ``core`` subfolder/namespace contains the basic building blocks of the library, this is the API to describe DAG's and internal/backend machinery for memory management. To include just libfork's core use ``#include <libfork/core.hpp>``.
 
-Control flow
---------------------------------
+Enums
+-----
 
-These function-like objects are used to control the flow of execution while building a directed acyclic task graph.
+.. doxygenenum:: lf::core::tag
 
-.. doxygenfunction:: lf::core::sync_wait
+Concepts and traits
+-----------------------------
 
-.. doxygenvariable:: lf::core::fork
+Libfork has a concept-driven API, built upon the following concepts.
 
-.. doxygenvariable:: lf::core::call
-
-.. doxygenvariable:: lf::core::join
-
-
-Concepts
-------------
-
-.. doxygenconcept:: lf::core::scheduler
+Building blocks
+~~~~~~~~~~~~~~~
 
 .. doxygenconcept:: lf::core::returnable
 
 .. doxygenconcept:: lf::core::dereferenceable
 
 .. doxygenconcept:: lf::core::quasi_pointer
 
+API
+~~~
+
 .. doxygenconcept:: lf::core::async_function_object
 
 .. doxygenconcept:: lf::core::first_arg
 
+.. doxygenconcept:: lf::core::scheduler
+
+.. doxygenconcept:: lf::core::co_allocable
+
+Functional
+~~~~~~~~~~
+
 .. doxygenconcept:: lf::core::async_invocable
 
 .. doxygenconcept:: lf::core::invocable
@@ -41,51 +44,64 @@ Concepts
 
 .. doxygenconcept:: lf::core::forkable
 
-.. doxygenconcept:: lf::core::co_allocable
+Utility
+.......
 
+.. doxygentypedef:: async_result_t
 
-Other
-----------------
 
-.. doxygenclass:: lf::core::defer
-    :members:
-    :undoc-members:
+Control flow
+--------------------------------
 
-.. doxygentypedef:: async_result_t
+.. doxygenfunction:: lf::core::sync_wait
 
-Classes
-------------
+Fork-join
+~~~~~~~~~~~~
 
-.. toctree::
-   :glob: 
-   :maxdepth: 2
+.. doxygenvariable:: lf::core::fork
 
-   core/task.rst
-   core/eventually.rst
+.. doxygenvariable:: lf::core::call
 
-Stack allocation
-------------------
+.. doxygenvariable:: lf::core::join
 
-.. doxygenfunction:: lf::core::co_new()
 
-.. doxygenfunction:: lf::core::co_new(std::size_t count)
+Classes
+----------------
 
-.. doxygenfunction:: lf::core::co_delete(T *ptr)
+Task
+~~~~
 
-.. doxygenfunction:: lf::core::co_delete(std::span<T, Extent> span)
+.. doxygenstruct:: lf::core::task
+    :members:
+    :undoc-members:
+
+Eventually
+~~~~~~~~~~
 
-Generated listing
----------------------
+.. doxygenclass:: lf::core::eventually
+   :members:
+   :undoc-members:
 
-.. toctree::
-   core.gen.rst
 
+.. doxygenclass:: lf::core::manual_eventually
+   :members:
+   :undoc-members:
 
+Defer
+~~~~~
 
+.. doxygenclass:: lf::core::defer
+    :members:
+    :undoc-members:
 
 
-   
+Stack allocation
+------------------
+
+.. doxygenfunction:: lf::core::co_new()
 
+.. doxygenfunction:: lf::core::co_new(std::size_t count)
 
+.. doxygenfunction:: lf::core::co_delete(T *ptr)
 
- 
+.. doxygenfunction:: lf::core::co_delete(std::span<T, Extent> span)

docs/api/core.rst

@@ -29,6 +29,8 @@ inline namespace core {
 
 /**
  * @brief Check is a type is suitable for allocation on libfork's stacks.
+ *
+ * This requires the type to be `std::default_initializable<T>` and have non-new-extended alignment.
  */
 template <typename T>
 concept co_allocable = std::default_initializable<T> && alignof(T) <= impl::k_new_align;

docs/api/core/eventually.rst

@@ -130,7 +130,7 @@ class eventually<T> : impl::immovable<eventually<T>> {
 // ------------------------------------------------------------------------ //
 
 /**
- * @brief A `manual_eventually<T>` is an `eventually<T>` which does not call destroy on destruction.
+ * @brief A `lf::manual_eventually<T>` is an `lf::eventually<T>` which does not call destroy on destruction.
  *
  * This is useful for writing exception safe fork-join code and should be considered an expert-only feature.
  */

docs/api/core/task.rst

@@ -53,8 +53,8 @@ concept quasi_pointer = std::default_initializable<I> && std::movable<I> && dere
  * object](https://en.cppreference.com/w/cpp/named_req/FunctionObject).
  *
  * An async function object is a function object that returns an `lf::task` when `operator()` is called.
- * with appropriate arguments. The call to `operator()` must create a coroutine. The first argument
- * of an async function must accept a deduced templated type that satisfies the `lf::core::first_arg` concept.
+ * with appropriate arguments. The call to `operator()` must create a libfork coroutine. The first argument
+ * of an async function must accept a deduced templated-type that satisfies the `lf::core::first_arg` concept.
  * The return type and invocability of an async function must be independent of the first argument except
  * for its tag value.
  *
@@ -68,7 +68,10 @@ concept async_function_object = std::is_object_v<F> && std::copy_constructible<F
 /**
  * @brief This describes the public-API of the first argument passed to an async function.
  *
- * An async functions' invocability and return type must be independent of their first argument.
+ * An async functions' invocability and return type must be independent of their first argument except for its
+ * tag value. A user may query the first argument's static member `tag` to obtain this value. Additionally, a
+ * user may query the first argument's static member function `context()` to obtain a pointer to the current
+ * workers `lf::context`.
  */
 template <typename T>
 concept first_arg = async_function_object<T> && requires (T arg) {

include/libfork/core/co_alloc.hpp

@@ -42,7 +42,7 @@ class manual_lifetime : immovable<manual_lifetime<T>> {
   }
 
   /**
-   * @brief Start lifetime of object.
+   * @brief Start lifetime of object at assignment.
    */
   template <typename U>
     requires std::constructible_from<T, U>