Adding upstream version 2.1.8~rc1.upstream/2.1.8_rc1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 134 insertions, 134 deletions

diff --git a/include/crm/common/resources.h b/include/crm/common/resources.h
index 043dc1c..9b38e68 100644
--- a/include/crm/common/resources.h
+++ b/include/crm/common/resources.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004-2023 the Pacemaker project contributors
+ * Copyright 2004-2024 the Pacemaker project contributors
  *
  * The version control history for this file may have further details.
  *
@@ -8,8 +8,9 @@
  */
 
 #ifndef PCMK__CRM_COMMON_RESOURCES__H
-#  define PCMK__CRM_COMMON_RESOURCES__H
+#define PCMK__CRM_COMMON_RESOURCES__H
 
+#include <stdbool.h>                    // bool
 #include <sys/types.h>                  // time_t
 #include <libxml/tree.h>                // xmlNode
 #include <glib.h>                       // gboolean, guint, GList, GHashTable
@@ -27,171 +28,156 @@ extern "C" {
  * \ingroup core
  */
 
-//! Resource variants supported by Pacemaker
+// Resource variants supported by Pacemaker
+//!@{
+//! \deprecated Do not use
 enum pe_obj_types {
     // Order matters: some code compares greater or lesser than
-    pcmk_rsc_variant_unknown    = -1,   //!< Unknown resource variant
-    pcmk_rsc_variant_primitive  = 0,    //!< Primitive resource
-    pcmk_rsc_variant_group      = 1,    //!< Group resource
-    pcmk_rsc_variant_clone      = 2,    //!< Clone resource
-    pcmk_rsc_variant_bundle     = 3,    //!< Bundle resource
+    pcmk_rsc_variant_unknown    = -1,   // Unknown resource variant
+    pcmk_rsc_variant_primitive  = 0,    // Primitive resource
+    pcmk_rsc_variant_group      = 1,    // Group resource
+    pcmk_rsc_variant_clone      = 2,    // Clone resource
+    pcmk_rsc_variant_bundle     = 3,    // Bundle resource
 
 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
-    //! \deprecated Use pcmk_rsc_variant_unknown instead
     pe_unknown      = pcmk_rsc_variant_unknown,
-
-    //! \deprecated Use pcmk_rsc_variant_primitive instead
     pe_native       = pcmk_rsc_variant_primitive,
-
-    //! \deprecated Use pcmk_rsc_variant_group instead
     pe_group        = pcmk_rsc_variant_group,
-
-    //! \deprecated Use pcmk_rsc_variant_clone instead
     pe_clone        = pcmk_rsc_variant_clone,
-
-    //! \deprecated Use pcmk_rsc_variant_bundle instead
     pe_container    = pcmk_rsc_variant_bundle,
 #endif
 };
 
-//! What resource needs before it can be recovered from a failed node
+// What resource needs before it can be recovered from a failed node
 enum rsc_start_requirement {
-    pcmk_requires_nothing   = 0,    //!< Resource can be recovered immediately
-    pcmk_requires_quorum    = 1,    //!< Resource can be recovered if quorate
-    pcmk_requires_fencing   = 2,    //!< Resource can be recovered after fencing
+    pcmk_requires_nothing   = 0,    // Resource can be recovered immediately
+    pcmk_requires_quorum    = 1,    // Resource can be recovered if quorate
+    pcmk_requires_fencing   = 2,    // Resource can be recovered after fencing
 
 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
-    //! \deprecated Use pcmk_requires_nothing instead
     rsc_req_nothing         = pcmk_requires_nothing,
-
-    //! \deprecated Use pcmk_requires_quorum instead
     rsc_req_quorum          = pcmk_requires_quorum,
-
-    //! \deprecated Use pcmk_requires_fencing instead
     rsc_req_stonith         = pcmk_requires_fencing,
 #endif
 };
 
-//! How to recover a resource that is incorrectly active on multiple nodes
+// How to recover a resource that is incorrectly active on multiple nodes
 enum rsc_recovery_type {
-    pcmk_multiply_active_restart    = 0,    //!< Stop on all, start on desired
-    pcmk_multiply_active_stop       = 1,    //!< Stop on all and leave stopped
-    pcmk_multiply_active_block      = 2,    //!< Do nothing to resource
-    pcmk_multiply_active_unexpected = 3,    //!< Stop unexpected instances
+    pcmk_multiply_active_restart    = 0,    // Stop on all, start on desired
+    pcmk_multiply_active_stop       = 1,    // Stop on all and leave stopped
+    pcmk_multiply_active_block      = 2,    // Do nothing to resource
+    pcmk_multiply_active_unexpected = 3,    // Stop unexpected instances
 
 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
-    //! \deprecated Use pcmk_multiply_active_restart instead
     recovery_stop_start             = pcmk_multiply_active_restart,
-
-    //! \deprecated Use pcmk_multiply_active_stop instead
     recovery_stop_only              = pcmk_multiply_active_stop,
-
-    //! \deprecated Use pcmk_multiply_active_block instead
     recovery_block                  = pcmk_multiply_active_block,
-
-    //! \deprecated Use pcmk_multiply_active_unexpected instead
     recovery_stop_unexpected        = pcmk_multiply_active_unexpected,
 #endif
 };
 
-//! Resource scheduling flags
+// Resource scheduling flags
 enum pcmk_rsc_flags {
-    //! No resource flags set (compare with equality rather than bit set)
+    // No resource flags set (compare with equality rather than bit set)
     pcmk_no_rsc_flags               = 0ULL,
 
-    //! Whether resource has been removed from the configuration
+    // Whether resource has been removed from the configuration
     pcmk_rsc_removed                = (1ULL << 0),
 
-    //! Whether resource is managed
+    // Whether resource is managed
     pcmk_rsc_managed                = (1ULL << 1),
 
-    //! Whether resource is blocked from further action
+    // Whether resource is blocked from further action
     pcmk_rsc_blocked                = (1ULL << 2),
 
-    //! Whether resource has been removed but has a container
+    // Whether resource has been removed but has a container
     pcmk_rsc_removed_filler         = (1ULL << 3),
 
-    //! Whether resource has clone notifications enabled
+    // Whether resource has clone notifications enabled
     pcmk_rsc_notify                 = (1ULL << 4),
 
-    //! Whether resource is not an anonymous clone instance
+    // Whether resource is not an anonymous clone instance
     pcmk_rsc_unique                 = (1ULL << 5),
 
-    //! Whether resource's class is "stonith"
+    // Whether resource's class is "stonith"
     pcmk_rsc_fence_device           = (1ULL << 6),
 
-    //! Whether resource can be promoted and demoted
+    // Whether resource can be promoted and demoted
     pcmk_rsc_promotable             = (1ULL << 7),
 
-    //! Whether resource has not yet been assigned to a node
+    // Whether resource has not yet been assigned to a node
     pcmk_rsc_unassigned             = (1ULL << 8),
 
-    //! Whether resource is in the process of being assigned to a node
+    // Whether resource is in the process of being assigned to a node
     pcmk_rsc_assigning              = (1ULL << 9),
 
-    //! Whether resource is in the process of modifying allowed node scores
+    // Whether resource is in the process of modifying allowed node scores
     pcmk_rsc_updating_nodes         = (1ULL << 10),
 
-    //! Whether resource is in the process of scheduling actions to restart
+    // Whether resource is in the process of scheduling actions to restart
     pcmk_rsc_restarting             = (1ULL << 11),
 
-    //! Whether resource must be stopped (instead of demoted) if it is failed
+    // Whether resource must be stopped (instead of demoted) if it is failed
     pcmk_rsc_stop_if_failed         = (1ULL << 12),
 
-    //! Whether a reload action has been scheduled for resource
+    // Whether a reload action has been scheduled for resource
     pcmk_rsc_reload                 = (1ULL << 13),
 
-    //! Whether resource is a remote connection allowed to run on a remote node
+    // Whether resource is a remote connection allowed to run on a remote node
     pcmk_rsc_remote_nesting_allowed = (1ULL << 14),
 
-    //! Whether resource has "critical" meta-attribute enabled
+    // Whether resource has \c PCMK_META_CRITICAL meta-attribute enabled
     pcmk_rsc_critical               = (1ULL << 15),
 
-    //! Whether resource is considered failed
+    // Whether resource is considered failed
     pcmk_rsc_failed                 = (1ULL << 16),
 
-    //! Flag for non-scheduler code to use to detect recursion loops
+    // Flag for non-scheduler code to use to detect recursion loops
     pcmk_rsc_detect_loop            = (1ULL << 17),
 
-    //! \deprecated Do not use
+    // \deprecated Do not use
     pcmk_rsc_runnable               = (1ULL << 18),
 
-    //! Whether resource has pending start action in history
+    // Whether resource has pending start action in history
     pcmk_rsc_start_pending          = (1ULL << 19),
 
-    //! \deprecated Do not use
+    // \deprecated Do not use
     pcmk_rsc_starting               = (1ULL << 20),
 
-    //! \deprecated Do not use
+    // \deprecated Do not use
     pcmk_rsc_stopping               = (1ULL << 21),
 
-    //! Whether resource is multiply active with recovery set to stop_unexpected
+    /*
+     * Whether resource is multiply active with recovery set to
+     * \c PCMK_VALUE_STOP_UNEXPECTED
+     */
     pcmk_rsc_stop_unexpected        = (1ULL << 22),
 
-    //! Whether resource is allowed to live-migrate
+    // Whether resource is allowed to live-migrate
     pcmk_rsc_migratable             = (1ULL << 23),
 
-    //! Whether resource has an ignorable failure
+    // Whether resource has an ignorable failure
     pcmk_rsc_ignore_failure         = (1ULL << 24),
 
-    //! Whether resource is an implicit container resource for a bundle replica
+    // Whether resource is an implicit container resource for a bundle replica
     pcmk_rsc_replica_container      = (1ULL << 25),
 
-    //! Whether resource, its node, or entire cluster is in maintenance mode
+    // Whether resource, its node, or entire cluster is in maintenance mode
     pcmk_rsc_maintenance            = (1ULL << 26),
 
-    //! \deprecated Do not use
+    // \deprecated Do not use
     pcmk_rsc_has_filler             = (1ULL << 27),
 
-    //! Whether resource can be started or promoted only on quorate nodes
+    // Whether resource can be started or promoted only on quorate nodes
     pcmk_rsc_needs_quorum           = (1ULL << 28),
 
-    //! Whether resource requires fencing before recovery if on unclean node
+    // Whether resource requires fencing before recovery if on unclean node
     pcmk_rsc_needs_fencing          = (1ULL << 29),
 
-    //! Whether resource can be started or promoted only on unfenced nodes
+    // Whether resource can be started or promoted only on unfenced nodes
     pcmk_rsc_needs_unfencing        = (1ULL << 30),
 };
+//!@}
 
 //! Search options for resources (exact resource ID always matches)
 enum pe_find {
@@ -259,12 +245,15 @@ enum pe_print_options {
 //!@}
 
 // Resource assignment methods (implementation defined by libpacemaker)
-//! This type should be considered internal to Pacemaker
+//! \deprecated Do not use (public access will be removed in a future release)
 typedef struct resource_alloc_functions_s pcmk_assignment_methods_t;
 
-//! Resource object methods
+// Resource object methods
+// @COMPAT Make this internal when we can break API backward compatibility
+//!@{
+//! \deprecated Do not use (public access will be removed in a future release)
 typedef struct resource_object_functions_s {
-    /*!
+    /*
      * \brief Parse variant-specific resource XML from CIB into struct members
      *
      * \param[in,out] rsc        Partially unpacked resource
@@ -274,7 +263,7 @@ typedef struct resource_object_functions_s {
      */
     gboolean (*unpack)(pcmk_resource_t *rsc, pcmk_scheduler_t *scheduler);
 
-    /*!
+    /*
      * \brief Search for a resource ID in a resource and its children
      *
      * \param[in] rsc      Search this resource and its children
@@ -287,7 +276,7 @@ typedef struct resource_object_functions_s {
     pcmk_resource_t *(*find_rsc)(pcmk_resource_t *rsc, const char *search,
                                  const pcmk_node_t *node, int flags);
 
-    /*!
+    /*
      * \brief Get value of a resource instance attribute
      *
      * \param[in,out] rsc        Resource to check
@@ -302,11 +291,11 @@ typedef struct resource_object_functions_s {
     char *(*parameter)(pcmk_resource_t *rsc, pcmk_node_t *node, gboolean create,
                        const char *name, pcmk_scheduler_t *scheduler);
 
-    //! \deprecated Do not use
+    // \deprecated Do not use
     void (*print)(pcmk_resource_t *rsc, const char *pre_text, long options,
                   void *print_data);
 
-    /*!
+    /*
      * \brief Check whether a resource is active
      *
      * \param[in] rsc  Resource to check
@@ -316,7 +305,7 @@ typedef struct resource_object_functions_s {
      */
     gboolean (*active)(pcmk_resource_t *rsc, gboolean all);
 
-    /*!
+    /*
      * \brief Get resource's current or assigned role
      *
      * \param[in] rsc      Resource to check
@@ -326,7 +315,7 @@ typedef struct resource_object_functions_s {
      */
     enum rsc_role_e (*state)(const pcmk_resource_t *rsc, gboolean current);
 
-    /*!
+    /*
      * \brief List nodes where a resource (or any of its children) is
      *
      * \param[in]  rsc      Resource to check
@@ -339,14 +328,14 @@ typedef struct resource_object_functions_s {
     pcmk_node_t *(*location)(const pcmk_resource_t *rsc, GList **list,
                              int current);
 
-    /*!
+    /*
      * \brief Free all memory used by a resource
      *
      * \param[in,out] rsc  Resource to free
      */
     void (*free)(pcmk_resource_t *rsc);
 
-    /*!
+    /*
      * \brief Increment cluster's instance counts for a resource
      *
      * Given a resource, increment its cluster's ninstances, disabled_resources,
@@ -356,7 +345,7 @@ typedef struct resource_object_functions_s {
      */
     void (*count)(pcmk_resource_t *rsc);
 
-    /*!
+    /*
      * \brief Check whether a given resource is in a list of resources
      *
      * \param[in] rsc           Resource ID to check for
@@ -369,7 +358,7 @@ typedef struct resource_object_functions_s {
     gboolean (*is_filtered)(const pcmk_resource_t *rsc, GList *only_rsc,
                             gboolean check_parent);
 
-    /*!
+    /*
      * \brief Find a node (and optionally count all) where resource is active
      *
      * \param[in]  rsc          Resource to check
@@ -378,14 +367,14 @@ typedef struct resource_object_functions_s {
      *
      * \return A node where the resource is active, preferring the source node
      *         if the resource is involved in a partial migration, or a clean,
-     *         online node if the resource's "requires" is "quorum" or
-     *         "nothing", otherwise NULL.
+     *         online node if the resource's \c PCMK_META_REQUIRES is
+     *         \c PCMK_VALUE_QUORUM or \c PCMK_VALUE_NOTHING, otherwise \c NULL.
      */
     pcmk_node_t *(*active_node)(const pcmk_resource_t *rsc,
                                 unsigned int *count_all,
                                 unsigned int *count_clean);
 
-    /*!
+    /*
      * \brief Get maximum resource instances per node
      *
      * \param[in] rsc  Resource to check
@@ -394,43 +383,53 @@ typedef struct resource_object_functions_s {
      */
     unsigned int (*max_per_node)(const pcmk_resource_t *rsc);
 } pcmk_rsc_methods_t;
+//!@}
 
-//! Implementation of pcmk_resource_t
+// Implementation of pcmk_resource_t
+// @COMPAT Make this internal when we can break API backward compatibility
+//!@{
+//! \deprecated Do not use (public access will be removed in a future release)
 struct pe_resource_s {
-    char *id;                           //!< Resource ID in configuration
-    char *clone_name;                   //!< Resource instance ID in history
+    // NOTE: sbd (as of at least 1.5.2) uses this
+    //! \deprecated Call pcmk_resource_id() instead
+    char *id;                           // Resource ID in configuration
 
-    //! Resource configuration (possibly expanded from template)
+    char *clone_name;                   // Resource instance ID in history
+
+    // Resource configuration (possibly expanded from template)
     xmlNode *xml;
 
-    //! Original resource configuration, if using template
+    // Original resource configuration, if using template
     xmlNode *orig_xml;
 
-    //! Configuration of resource operations (possibly expanded from template)
+    // Configuration of resource operations (possibly expanded from template)
     xmlNode *ops_xml;
 
-    pcmk_scheduler_t *cluster;          //!< Cluster that resource is part of
-    pcmk_resource_t *parent;            //!< Resource's parent resource, if any
-    enum pe_obj_types variant;          //!< Resource variant
-    void *variant_opaque;               //!< Variant-specific (and private) data
-    pcmk_rsc_methods_t *fns;            //!< Resource object methods
-    pcmk_assignment_methods_t *cmds;    //!< Resource assignment methods
-
-    enum rsc_recovery_type recovery_type;   //!< How to recover if failed
-
-    enum pe_restart restart_type;   //!< \deprecated Do not use
-    int priority;                   //!< Configured priority
-    int stickiness;                 //!< Extra preference for current node
-    int sort_index;                 //!< Promotion score on assigned node
-    int failure_timeout;            //!< Failure timeout
-    int migration_threshold;        //!< Migration threshold
-    guint remote_reconnect_ms;      //!< Retry interval for remote connections
-    char *pending_task;             //!< Pending action in history, if any
-    unsigned long long flags;       //!< Group of enum pcmk_rsc_flags
+    pcmk_scheduler_t *cluster;          // Cluster that resource is part of
+    pcmk_resource_t *parent;            // Resource's parent resource, if any
+    enum pe_obj_types variant;          // Resource variant
+    void *variant_opaque;               // Variant-specific (and private) data
+    pcmk_rsc_methods_t *fns;            // Resource object methods
+    pcmk_assignment_methods_t *cmds;    // Resource assignment methods
+
+    enum rsc_recovery_type recovery_type;   // How to recover if failed
+
+    enum pe_restart restart_type;   // \deprecated Do not use
+    int priority;                   // Configured priority
+    int stickiness;                 // Extra preference for current node
+    int sort_index;                 // Promotion score on assigned node
+    int failure_timeout;            // Failure timeout
+    int migration_threshold;        // Migration threshold
+    guint remote_reconnect_ms;      // Retry interval for remote connections
+    char *pending_task;             // Pending action in history, if any
+
+    // NOTE: sbd (as of at least 1.5.2) uses this
+    //! \deprecated Call pcmk_resource_is_managed() instead
+    unsigned long long flags;       // Group of enum pcmk_rsc_flags
 
     // @TODO Merge these into flags
-    gboolean is_remote_node;        //!< Whether this is a remote connection
-    gboolean exclusive_discover;    //!< Whether exclusive probing is enabled
+    gboolean is_remote_node;        // Whether this is a remote connection
+    gboolean exclusive_discover;    // Whether exclusive probing is enabled
 
     /* Pay special attention to whether you want to use rsc_cons_lhs and
      * rsc_cons directly, which include only colocations explicitly involving
@@ -439,54 +438,51 @@ struct pe_resource_s {
      * colocations involving the resource's ancestors as well.
      */
 
-    //!@{
-    //! This field should be treated as internal to Pacemaker
     GList *rsc_cons_lhs;      // Colocations of other resources with this one
     GList *rsc_cons;          // Colocations of this resource with others
     GList *rsc_location;      // Location constraints for resource
     GList *actions;           // Actions scheduled for resource
     GList *rsc_tickets;       // Ticket constraints for resource
-    //!@}
 
-    pcmk_node_t *allocated_to;  //!< Node resource is assigned to
+    pcmk_node_t *allocated_to;  // Node resource is assigned to
 
-    //! The destination node, if migrate_to completed but migrate_from has not
+    // The destination node, if migrate_to completed but migrate_from has not
     pcmk_node_t *partial_migration_target;
 
-    //! The source node, if migrate_to completed but migrate_from has not
+    // The source node, if migrate_to completed but migrate_from has not
     pcmk_node_t *partial_migration_source;
 
-    //! Nodes where resource may be active
+    // Nodes where resource may be active
     GList *running_on;
 
-    //! Nodes where resource has been probed (key is node ID, not name)
+    // Nodes where resource has been probed (key is node ID, not name)
     GHashTable *known_on;
 
-    //! Nodes where resource may run (key is node ID, not name)
+    // Nodes where resource may run (key is node ID, not name)
     GHashTable *allowed_nodes;
 
-    enum rsc_role_e role;           //!< Resource's current role
-    enum rsc_role_e next_role;      //!< Resource's scheduled next role
+    enum rsc_role_e role;           // Resource's current role
+    enum rsc_role_e next_role;      // Resource's scheduled next role
 
-    GHashTable *meta;               //!< Resource's meta-attributes
-    GHashTable *parameters;         //!< \deprecated Use pe_rsc_params() instead
-    GHashTable *utilization;        //!< Resource's utilization attributes
+    GHashTable *meta;               // Resource's meta-attributes
+    GHashTable *parameters;         // \deprecated Use pe_rsc_params() instead
+    GHashTable *utilization;        // Resource's utilization attributes
 
-    GList *children;                //!< Resource's child resources, if any
+    GList *children;                // Resource's child resources, if any
 
     // Source nodes where stop is needed after migrate_from and migrate_to
     GList *dangling_migrations;
 
-    pcmk_resource_t *container;     //!< Resource containing this one, if any
-    GList *fillers;                 //!< Resources contained by this one, if any
+    pcmk_resource_t *container;     // Resource containing this one, if any
+    GList *fillers;                 // Resources contained by this one, if any
 
     // @COMPAT These should be made const at next API compatibility break
-    pcmk_node_t *pending_node;      //!< Node on which pending_task is happening
-    pcmk_node_t *lock_node;         //!< Resource shutdown-locked to this node
+    pcmk_node_t *pending_node;      // Node on which pending_task is happening
+    pcmk_node_t *lock_node;         // Resource shutdown-locked to this node
 
-    time_t lock_time;               //!< When shutdown lock started
+    time_t lock_time;               // When shutdown lock started
 
-    /*!
+    /*
      * Resource parameters may have node-attribute-based rules, which means the
      * values can vary by node. This table has node names as keys and parameter
      * name/value tables as values. Use pe_rsc_params() to get the table for a
@@ -494,6 +490,10 @@ struct pe_resource_s {
      */
     GHashTable *parameter_cache;
 };
+//!@}
+
+const char *pcmk_resource_id(const pcmk_resource_t *rsc);
+bool pcmk_resource_is_managed(const pcmk_resource_t *rsc);
 
 #ifdef __cplusplus
 }