job-list: add state matching library

Problem: In job-list we store jobs on three lists, pending,
running, and inactive.  If we begin to use RFC31 constraints
to filter jobs, it would be inefficient to scan all three lists
for every job list query.

Solution: Add a job state matching library.  It will determine if
jobs in the pending, running, or inactive state are possible given
the job constraint sent with the job-list query.  For example:

states=pending AND userid=42

In the above constraint, a job in a pending state can possibly be
matched to this constraint, so it is worthwhile to scan the pending
job list for jobs with userid=42.  However, it is impossible for
a job in running or inactive state to match at all, so they should
not be scanned.

This will allow job-list queries to run more efficiently if entire
lists can be skipped if it is impossible for any jobs on those lists
to be matched to a constraint.

Add unit tests.

Author: chu11

src/modules/job-list/Makefile.am

@@ -31,11 +31,16 @@ libjob_list_la_SOURCES = \
 	stats.h \
 	stats.c \
 	match.h \
-	match.c
+	match.c \
+	state_match.h \
+	state_match.c \
+	match_util.h \
+	match_util.c
 
 TESTS = \
 	test_job_data.t \
-	test_match.t
+	test_match.t \
+	test_state_match.t
 
 test_ldadd = \
 	$(builddir)/libjob-list.la \
@@ -76,6 +81,14 @@ test_match_t_LDADD = \
 test_match_t_LDFLAGS = \
 	$(test_ldflags)
 
+test_state_match_t_SOURCES = test/state_match.c
+test_state_match_t_CPPFLAGS = \
+	$(test_cppflags)
+test_state_match_t_LDADD = \
+	$(test_ldadd)
+test_state_match_t_LDFLAGS = \
+	$(test_ldflags)
+
 EXTRA_DIST = \
 	test/R/1node_1core.R \
 	test/R/1node_4core.R \

src/modules/job-list/match.c

@@ -21,12 +21,9 @@
 #include "ccan/str/str.h"
 
 #include "match.h"
+#include "match_util.h"
 
-/* identical to czmq_destructor, czmq.h happens to define a
- * conflicting symbol we use */
-typedef void (destructor_f) (void **item);
 typedef bool (*match_f) (struct list_constraint *, const struct job *);
-typedef int (*array_to_bitmask_f) (json_t *, flux_error_t *);
 
 struct list_constraint {
     zlistx_t *values;
@@ -302,45 +299,6 @@ static bool match_states (struct list_constraint *c, const struct job *job)
     return ((*states) & job->state);
 }
 
-static int array_to_states_bitmask (json_t *values, flux_error_t *errp)
-{
-    int states = 0;
-    json_t *entry;
-    size_t index;
-    int valid_states = (FLUX_JOB_STATE_NEW
-                        | FLUX_JOB_STATE_PENDING
-                        | FLUX_JOB_STATE_RUNNING
-                        | FLUX_JOB_STATE_INACTIVE);
-
-    json_array_foreach (values, index, entry) {
-        flux_job_state_t state;
-        if (json_is_string (entry)) {
-            const char *statestr = json_string_value (entry);
-            if (flux_job_strtostate (statestr, &state) < 0) {
-                errprintf (errp,
-                           "invalid states value '%s' specified",
-                           statestr);
-                return -1;
-            }
-        }
-        else if (json_is_integer (entry)) {
-            state = json_integer_value (entry);
-            if (state & ~valid_states) {
-                errprintf (errp,
-                           "invalid states value '%Xh' specified",
-                           state);
-                return -1;
-            }
-        }
-        else {
-            errprintf (errp, "states value invalid type");
-            return -1;
-        }
-        states |= state;
-    }
-    return states;
-}
-
 static struct list_constraint *create_states_constraint (json_t *values,
                                                          flux_error_t *errp)
 {

src/modules/job-list/match_util.c

@@ -0,0 +1,64 @@
+/************************************************************\
+ * Copyright 2023 Lawrence Livermore National Security, LLC
+ * (c.f. AUTHORS, NOTICE.LLNS, COPYING)
+ *
+ * This file is part of the Flux resource manager framework.
+ * For details, see https://github.com/flux-framework.
+ *
+ * SPDX-License-Identifier: LGPL-3.0
+\************************************************************/
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <jansson.h>
+
+#include "src/common/libutil/errprintf.h"
+
+#include "match_util.h"
+
+int array_to_states_bitmask (json_t *values, flux_error_t *errp)
+{
+    int states = 0;
+    json_t *entry;
+    size_t index;
+    int valid_states = (FLUX_JOB_STATE_NEW
+                        | FLUX_JOB_STATE_PENDING
+                        | FLUX_JOB_STATE_RUNNING
+                        | FLUX_JOB_STATE_INACTIVE);
+
+    json_array_foreach (values, index, entry) {
+        flux_job_state_t state;
+        if (json_is_string (entry)) {
+            const char *statestr = json_string_value (entry);
+            if (flux_job_strtostate (statestr, &state) < 0) {
+                errprintf (errp,
+                           "invalid states value '%s' specified",
+                           statestr);
+                return -1;
+            }
+        }
+        else if (json_is_integer (entry)) {
+            state = json_integer_value (entry);
+            if (state & ~valid_states) {
+                errprintf (errp,
+                           "invalid states value '%Xh' specified",
+                           state);
+                return -1;
+            }
+        }
+        else {
+            errprintf (errp, "states value invalid type");
+            return -1;
+        }
+        states |= state;
+    }
+    return states;
+}
+
+/* vi: ts=4 sw=4 expandtab
+ */

src/modules/job-list/match_util.h

@@ -0,0 +1,29 @@
+/************************************************************\
+ * Copyright 2023 Lawrence Livermore National Security, LLC
+ * (c.f. AUTHORS, NOTICE.LLNS, COPYING)
+ *
+ * This file is part of the Flux resource manager framework.
+ * For details, see https://github.com/flux-framework.
+ *
+ * SPDX-License-Identifier: LGPL-3.0
+\************************************************************/
+
+#ifndef HAVE_JOB_LIST_MATCH_UTIL_H
+#define HAVE_JOB_LIST_MATCH_UTIL_H 1
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <flux/core.h> /* flux_error_t */
+#include <jansson.h>
+
+/* identical to czmq_destructor, czmq.h happens to define a
+ * conflicting symbol we use */
+typedef void (destructor_f) (void **item);
+
+typedef int (*array_to_bitmask_f) (json_t *, flux_error_t *);
+
+int array_to_states_bitmask (json_t *values, flux_error_t *errp);
+
+#endif /* !HAVE_JOB_LIST_MATCH_UTIL_H */