diff options
Diffstat (limited to 'doc/sphinx/Pacemaker_Development')
| -rw-r--r-- | doc/sphinx/Pacemaker_Development/c.rst | 14 | ||||
| -rw-r--r-- | doc/sphinx/Pacemaker_Development/components.rst | 52 | ||||
| -rw-r--r-- | doc/sphinx/Pacemaker_Development/helpers.rst | 5 |
3 files changed, 40 insertions, 31 deletions
diff --git a/doc/sphinx/Pacemaker_Development/c.rst b/doc/sphinx/Pacemaker_Development/c.rst index 66ce3b2..b03ddae 100644 --- a/doc/sphinx/Pacemaker_Development/c.rst +++ b/doc/sphinx/Pacemaker_Development/c.rst @@ -225,8 +225,8 @@ a ``GHashTable *`` member, the argument should be marked as ``[in,out]`` if the function inserts data into the table, even if the struct members themselves are not changed. However, an argument is not ``[in,out]`` if something reachable via the argument is modified via a separate argument. For example, both -``pe_resource_t`` and ``pe_node_t`` contain pointers to their -``pe_working_set_t`` and thus indirectly to each other, but if the function +``pcmk_resource_t`` and ``pcmk_node_t`` contain pointers to their +``pcmk_scheduler_t`` and thus indirectly to each other, but if the function modifies the resource via the resource argument, the node argument does not have to be ``[in,out]``. @@ -745,10 +745,20 @@ readability and logging consistency. Functions ######### +Function Naming +_______________ + Function names should be unique across the entire project, to allow for individual tracing via ``PCMK_trace_functions``, and make it easier to search code and follow detail logs. +A common function signature is a comparison function that returns 0 if its +arguments are equal for sorting purposes, -1 if the first argument should sort +first, and 1 is the second argument should sort first. Such a function should +have ``cmp`` in its name, to parallel ``strcmp()``; ``sort`` should only be +used in the names of functions that sort an entire list (typically using a +``cmp`` function). + Function Definitions ____________________ diff --git a/doc/sphinx/Pacemaker_Development/components.rst b/doc/sphinx/Pacemaker_Development/components.rst index e14df26..5086fa8 100644 --- a/doc/sphinx/Pacemaker_Development/components.rst +++ b/doc/sphinx/Pacemaker_Development/components.rst @@ -301,7 +301,7 @@ directly. This allows them to run using a ``CIB_file`` without the cluster needing to be active. The main entry point for the scheduler code is -``lib/pacemaker/pcmk_sched_allocate.c:pcmk__schedule_actions()``. It sets +``lib/pacemaker/pcmk_scheduler.c:pcmk__schedule_actions()``. It sets defaults and calls a series of functions for the scheduling. Some key steps: * ``unpack_cib()`` parses most of the CIB XML into data structures, and @@ -315,7 +315,7 @@ defaults and calls a series of functions for the scheduling. Some key steps: the CIB status section. This is used to decide whether certain actions need to be done, such as deleting orphan resources, forcing a restart when a resource definition changes, etc. -* ``allocate_resources()`` assigns resources to nodes. +* ``assign_resources()`` assigns resources to nodes. * ``schedule_resource_actions()`` schedules resource-specific actions (which might or might not end up in the final graph). * ``pcmk__apply_orderings()`` processes ordering constraints in order to modify @@ -335,7 +335,7 @@ Working with the scheduler is difficult. Challenges include: * It produces an insane amount of log messages at debug and trace levels. You can put resource ID(s) in the ``PCMK_trace_tags`` environment variable to enable trace-level messages only when related to specific resources. -* Different parts of the main ``pe_working_set_t`` structure are finalized at +* Different parts of the main ``pcmk_scheduler_t`` structure are finalized at different points in the scheduling process, so you have to keep in mind whether information you're using at one point of the code can possibly change later. For example, data unpacked from the CIB can safely be used anytime @@ -347,24 +347,24 @@ Working with the scheduler is difficult. Challenges include: .. index:: - single: pe_working_set_t + single: pcmk_scheduler_t Cluster Working Set ___________________ -The main data object for the scheduler is ``pe_working_set_t``, which contains +The main data object for the scheduler is ``pcmk_scheduler_t``, which contains all information needed about nodes, resources, constraints, etc., both as the raw CIB XML and parsed into more usable data structures, plus the resulting -transition graph XML. The variable name is usually ``data_set``. +transition graph XML. The variable name is usually ``scheduler``. .. index:: - single: pe_resource_t + single: pcmk_resource_t Resources _________ -``pe_resource_t`` is the data object representing cluster resources. A resource -has a variant: primitive (a.k.a. native), group, clone, or bundle. +``pcmk_resource_t`` is the data object representing cluster resources. A +resource has a variant: primitive (a.k.a. native), group, clone, or bundle. The resource object has members for two sets of methods, ``resource_object_functions_t`` from the ``libpe_status`` public API, and @@ -374,45 +374,45 @@ The resource object has members for two sets of methods, The object functions have basic capabilities such as unpacking the resource XML, and determining the current or planned location of the resource. -The allocation functions have more obscure capabilities needed for scheduling, +The assignment functions have more obscure capabilities needed for scheduling, such as processing location and ordering constraints. For example, ``pcmk__create_internal_constraints()`` simply calls the ``internal_constraints()`` method for each top-level resource in the cluster. .. index:: - single: pe_node_t + single: pcmk_node_t Nodes _____ -Allocation of resources to nodes is done by choosing the node with the highest +Assignment of resources to nodes is done by choosing the node with the highest score for a given resource. The scheduler does a bunch of processing to -generate the scores, then the actual allocation is straightforward. +generate the scores, then the actual assignment is straightforward. -Node lists are frequently used. For example, ``pe_working_set_t`` has a +Node lists are frequently used. For example, ``pcmk_scheduler_t`` has a ``nodes`` member which is a list of all nodes in the cluster, and -``pe_resource_t`` has a ``running_on`` member which is a list of all nodes on -which the resource is (or might be) active. These are lists of ``pe_node_t`` +``pcmk_resource_t`` has a ``running_on`` member which is a list of all nodes on +which the resource is (or might be) active. These are lists of ``pcmk_node_t`` objects. -The ``pe_node_t`` object contains a ``struct pe_node_shared_s *details`` member -with all node information that is independent of resource allocation (the node -name, etc.). +The ``pcmk_node_t`` object contains a ``struct pe_node_shared_s *details`` +member with all node information that is independent of resource assignment +(the node name, etc.). The working set's ``nodes`` member contains the original of this information. -All other node lists contain copies of ``pe_node_t`` where only the ``details`` -member points to the originals in the working set's ``nodes`` list. In this -way, the other members of ``pe_node_t`` (such as ``weight``, which is the node -score) may vary by node list, while the common details are shared. +All other node lists contain copies of ``pcmk_node_t`` where only the +``details`` member points to the originals in the working set's ``nodes`` list. +In this way, the other members of ``pcmk_node_t`` (such as ``weight``, which is +the node score) may vary by node list, while the common details are shared. .. index:: - single: pe_action_t + single: pcmk_action_t single: pe_action_flags Actions _______ -``pe_action_t`` is the data object representing actions that might need to be +``pcmk_action_t`` is the data object representing actions that might need to be taken. These could be resource actions, cluster-wide actions such as fencing a node, or "pseudo-actions" which are abstractions used as convenient points for ordering other actions against. @@ -443,7 +443,7 @@ Colocation constraints come into play in these parts of the scheduler code: * When choosing roles for promotable clone instances, so colocations involving a specific role can affect which instances are promoted -The resource allocation functions have several methods related to colocations: +The resource assignment functions have several methods related to colocations: * ``apply_coloc_score():`` This applies a colocation's score to either the dependent's allowed node scores (if called while resources are being diff --git a/doc/sphinx/Pacemaker_Development/helpers.rst b/doc/sphinx/Pacemaker_Development/helpers.rst index 3fcb48d..6bd1926 100644 --- a/doc/sphinx/Pacemaker_Development/helpers.rst +++ b/doc/sphinx/Pacemaker_Development/helpers.rst @@ -476,14 +476,13 @@ The Pacemaker build process uses ``lcov`` and special make targets to generate an HTML coverage report that can be inspected with any web browser. To start, you'll need to install the ``lcov`` package which is included in most -distributions. Next, reconfigure and rebuild the source tree: +distributions. Next, reconfigure the source tree: .. code-block:: none $ ./configure --with-coverage - $ make -Then simply run ``make coverage``. This will do the same thing as ``make check``, +Then run ``make -C devel coverage``. This will do the same thing as ``make check``, but will generate a bunch of intermediate files as part of the compiler's output. Essentially, the coverage tools run all the unit tests and make a note if a given line if code is executed as a part of some test program. This will include not |