libidset: public lib for numerically sorted, non-negative integer sets

configure.ac

@@ -303,6 +303,7 @@ AC_CONFIG_FILES( \
   src/common/libsubprocess/Makefile \
   src/common/libcompat/Makefile \
   src/common/liboptparse/Makefile \
+  src/common/libidset/Makefile \
   src/common/libjobspec/Makefile \
   src/common/libjobspec/flux-jobspec.pc \
   src/common/libtomlc99/Makefile \
@@ -334,6 +335,7 @@ AC_CONFIG_FILES( \
   etc/flux-core.pc \
   etc/flux-pmi.pc \
   etc/flux-optparse.pc \
+  etc/flux-idset.pc \
   etc/flux.service \
   doc/Makefile \
   doc/man1/Makefile \

doc/man3/Makefile.am

@@ -47,7 +47,8 @@ MAN3_FILES_PRIMARY = \
 	flux_kvs_txn_create.3 \
 	flux_kvs_namespace_create.3 \
 	flux_kvs_namespace_list.3 \
-	flux_kvs_set_namespace.3
+	flux_kvs_set_namespace.3 \
+	idset_create.3
 
 # These files are generated as roff .so includes of a primary page.
 # A2X handles this automatically if mentioned in NAME section
@@ -148,7 +149,10 @@ MAN3_FILES_SECONDARY = \
 	flux_kvs_namespace_itr_next.3 \
 	flux_kvs_namespace_itr_rewind.3 \
 	flux_kvs_namespace_itr_destroy.3 \
-	flux_kvs_get_namespace.3
+	flux_kvs_get_namespace.3 \
+	idset_destroy.3 \
+	idset_encode.3 \
+	idset_decode.3
 
 ADOC_FILES  = $(MAN3_FILES_PRIMARY:%.3=%.adoc)
 XML_FILES   = $(MAN3_FILES_PRIMARY:%.3=%.xml)
@@ -270,6 +274,9 @@ flux_kvs_namespace_itr_next.3: flux_kvs_namespace_list.3
 flux_kvs_namespace_itr_rewind.3: flux_kvs_namespace_list.3
 flux_kvs_namespace_itr_destroy.3: flux_kvs_namespace_list.3
 flux_kvs_get_namespace.3: flux_kvs_set_namespace.3
+idset_destroy.3: idset_create.3
+idset_encode.3: idset_create.3
+idset_decode.3: idset_create.3
 
 flux_open.3: topen.c
 flux_send.3: tsend.c

doc/man3/idset_create.adoc

@@ -0,0 +1,119 @@
+idset_create(3)
+===============
+:doctype: manpage
+
+
+NAME
+----
+idset_create, idset_destroy, idset_encode, idset_decode - Manipulate numerically sorted sets of non-negative integers
+
+
+SYNOPSIS
+--------
+#include <flux/idset.h>
+
+struct idset *idset_create (size_t slots, int flags);
+
+void idset_destroy (struct idset *idset);
+
+char *idset_encode (const struct idset *idset, int flags);
+
+struct idset *idset_decode (const char *s);
+
+USAGE
+-----
+
+cc [flags] files -lflux-idset [libraries]
+
+DESCRIPTION
+-----------
+
+An idset is a set of numerically sorted, non-negative integers.
+It is internally represented as a Van Embde Boas (or vEB) tree.
+Functionally it behaves like a bitmap, and has space efficiency
+comparable to a bitmap, but performs operations (insert, delete,
+lookup, findNext, findPrevious) in O(log(m)) time, where pow (2,m)
+is the number of slots in the idset.
+
+`idset_create()` creates an idset.  'slots' specifies the highest
+numbered 'id' it can hold, plus one.  The size is fixed unless
+'flags' specify otherwise (see FLAGS below).
+
+`idset_destroy()` destroys an idset.
+
+`idset_decode ()` creates an idset from a string 's'.  The string may
+have been produced by `idset_encode()`.  It must consist of comma-separated
+non-negative integer id's, and may also contain hyphenated ranges.
+If enclosed in square brackets, the brackets are ignored.  Some examples
+of valid input strings are:
+
+  1,2,5,4
+
+  1-4,7,9-10
+
+  42
+
+  [99-101]
+
+`idset_encode()` creates a string from 'idset'.  The string contains
+a comma-separated list of id's, potentially modified by 'flags'
+(see FLAGS below).
+
+FLAGS
+-----
+
+IDSET_FLAG_AUTOGROW::
+Valid for `idset_create()` only.  If set, the idset will grow to
+accommodate any id inserted into it. The internal vEB tree is doubled
+in size until until the new id can be inserted.  Resizing is a costly
+operation that requires all id's in the old tree to be inserted into
+the new one.
+
+IDSET_FLAG_BRACKETS::
+Valid for `idset_encode()` only.  If set, the encoded string will be
+enclosed in brackets, unless the idset is a singleton (contains only
+one id).
+
+IDSET_FLAG_RANGE::
+Valid for `idset_encode()` only.  If set, any consecutive id's are
+compressed into hyphenated ranges in the encoded string.
+
+RETURN VALUE
+------------
+
+`idset_create()` and `idset_encode()` return an idset on success
+which must be freed with `idset_destroy()`.  On error, NULL is
+returned with errno set.
+
+`idset_decode()` returns a string on success which must be freed
+with `free()`.  On error, NULL is returned with errno set.
+
+ERRORS
+------
+
+EINVAL::
+One or more arguments were invalid.
+
+ENOMEM::
+Out of memory.
+
+
+AUTHOR
+------
+This page is maintained by the Flux community.
+
+
+RESOURCES
+---------
+Github: <http://github.com/flux-framework>
+
+
+COPYRIGHT
+---------
+include::COPYRIGHT.adoc[]
+
+
+SEE ALSO
+--------
+flux-dmesg(1), flux-logger(1),
+https://tools.ietf.org/html/rfc5424[RFC 5424 The Syslog Protocol]

doc/test/spell.en.pws

@@ -411,3 +411,11 @@ EOVERFLOW
 itr
 JOBIDS
 ns
+Embde
+idset
+AUTOGROW
+findNext
+findPrevious
+vEB
+lflux
+resizing

etc/Makefile.am

@@ -35,7 +35,7 @@ clean-local:
 	-rm -rf flux
 
 if WITH_PKG_CONFIG
-pkgconfig_DATA = flux-core.pc flux-pmi.pc flux-optparse.pc
+pkgconfig_DATA = flux-core.pc flux-pmi.pc flux-optparse.pc flux-idset.pc
 endif
 
 EXTRA_DIST = \

etc/flux-idset.pc.in

@@ -0,0 +1,10 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@
+
+Name: flux-core
+Description: Flux Resource Manager ID Set Library
+Version: @PACKAGE_VERSION@
+Libs: -L${libdir} -lflux-idset
+Cflags: -I${includedir}

src/common/Makefile.am

@@ -11,6 +11,7 @@ SUBDIRS = libtap \
 	  libsubprocess \
 	  libcompat \
 	  liboptparse \
+	  libidset \
 	  libtomlc99 \
 	  libkz
 
@@ -41,7 +42,7 @@ libflux_internal_la_LIBADD = \
 	$(LIBDL) $(LIBRT)
 libflux_internal_la_LDFLAGS = $(san_ld_zdef_flag)
 
-lib_LTLIBRARIES = libflux-core.la libflux-optparse.la
+lib_LTLIBRARIES = libflux-core.la libflux-optparse.la libflux-idset.la
 if ENABLE_JOBSPEC
 lib_LTLIBRARIES += libflux-jobspec.la
 endif
@@ -68,6 +69,15 @@ libflux_optparse_la_LDFLAGS = \
 	-shared -export-dynamic --disable-static \
 	$(san_ld_zdef_flag)
 
+libflux_idset_la_SOURCES =
+libflux_idset_la_LIBADD = \
+	$(builddir)/libidset/libidset.la \
+	$(builddir)/libutil/veb.lo
+libflux_idset_la_LDFLAGS = \
+        -Wl,--version-script=$(srcdir)/libflux-idset.map \
+	-shared -export-dynamic --disable-static \
+	$(san_ld_zdef_flag)
+
 if ENABLE_JOBSPEC
 libflux_jobspec_la_SOURCES =
 libflux_jobspec_la_LIBADD = $(builddir)/libjobspec/libjobspec.la
@@ -93,4 +103,9 @@ libpmi2_la_LDFLAGS = \
 	$(san_ld_zdef_flag)
 
 
-EXTRA_DIST = libflux-core.map libflux-optparse.map libpmi.map libpmi2.map
+EXTRA_DIST = \
+	libflux-core.map \
+	libflux-optparse.map \
+	libflux-idset.map \
+	libpmi.map \
+	libpmi2.map

src/common/libflux-idset.map

@@ -0,0 +1,5 @@
+{ global:
+    idset_*;
+    local: *;
+};
+

src/common/libidset/Makefile.am

@@ -0,0 +1,36 @@
+AM_CFLAGS = \
+	$(WARNING_CFLAGS) \
+	$(CODE_COVERAGE_CFLAGS)
+
+AM_LDFLAGS = \
+	$(CODE_COVERAGE_LIBS)
+
+AM_CPPFLAGS = \
+	-I$(top_srcdir) -I$(top_srcdir)/src/include \
+	$(ZMQ_CFLAGS)
+
+noinst_LTLIBRARIES = libidset.la
+fluxinclude_HEADERS = idset.h
+libidset_la_SOURCES = idset.c
+
+libidset_la_CPPFLAGS = \
+	$(AM_CPPFLAGS)
+libidset_la_LDFLAGS = \
+	-avoid-version -module -shared -export-dynamic \
+	$(AM_LDFLAGS)
+
+
+TESTS = test_idset.t
+
+check_PROGRAMS = $(TESTS)
+
+TEST_EXTENSIONS = .t
+T_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
+       $(top_srcdir)/config/tap-driver.sh
+
+test_idset_t_SOURCES = test/idset.c
+test_idset_t_CPPFLAGS = $(AM_CPPFLAGS)
+test_idset_t_LDADD = \
+	$(top_builddir)/src/common/libtap/libtap.la \
+	$(top_builddir)/src/common/libidset/libidset.la \
+	$(top_builddir)/src/common/libutil/libutil.la