DAOS-16924 dfs: new readdir API

src/client/dfs/dcache.c

@@ -1,5 +1,6 @@
 /**
  * (C) Copyright 2022-2024 Intel Corporation.
+ * (C) Copyright 2025 Hewlett Packard Enterprise Development LP
  *
  * SPDX-License-Identifier: BSD-2-Clause-Patent
  */
@@ -75,7 +76,7 @@ typedef void (*drec_decref_fn_t)(dfs_dcache_t *, dfs_obj_t *);
 typedef void (*drec_del_at_fn_t)(dfs_dcache_t *, dfs_obj_t *);
 typedef int (*drec_del_fn_t)(dfs_dcache_t *, char *, dfs_obj_t *);
 
-/** DFS directory cache */
+/** DFS dentry cache */
 struct dfs_dcache {
 	/** Cached DAOS file system */
 	dfs_t              *dd_dfs;
@@ -990,3 +991,6 @@ drec_del(dfs_dcache_t *dcache, char *path, dfs_obj_t *parent)
 
 	return dcache->drec_del_fn(dcache, path, parent);
 }
+
+// dcache_readdir(dfs_dcache_t *dcache, dfs_obj_t *obj, dfs_dir_anchor_t *anchor, struct dirent dir)
+// {}

src/client/dfs/dfs_internal.h

@@ -1,5 +1,6 @@
 /**
  * (C) Copyright 2019-2024 Intel Corporation.
+ * (C) Copyright 2025 Hewlett Packard Enterprise Development LP
  *
  * SPDX-License-Identifier: BSD-2-Clause-Patent
  */
@@ -274,6 +275,15 @@ struct dfs_mnt_hdls {
 	int           type;
 };
 
+/** readdir anchor for dfs_readdir2(). If dcache is disabled, the only valid setting is the
+ * daos_anchor_t. */
+struct dfs_dir_anchor {
+	dfs_obj_t    *dda_dir;
+	daos_anchor_t dda_anchor_int;
+	size_t        dda_bucket_id;
+	off_t         dda_bucket_offset;
+};
+
 static inline bool
 tspec_gt(struct timespec l, struct timespec r)
 {

src/client/dfs/readdir.c

@@ -1,5 +1,6 @@
 /**
  * (C) Copyright 2018-2024 Intel Corporation.
+ * (C) Copyright 2025 Hewlett Packard Enterprise Development LP
  *
  * SPDX-License-Identifier: BSD-2-Clause-Patent
  */
@@ -9,6 +10,7 @@
 #define D_LOGFAC DD_FAC(dfs)
 
 #include <daos/common.h>
+#include <daos/object.h>
 
 #include "dfs_internal.h"
 
@@ -113,6 +115,78 @@ dfs_readdirplus(dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr,
 	return readdir_int(dfs, obj, anchor, nr, dirs, stbufs);
 }
 
+int
+dfs_dir_anchor_init(dfs_obj_t *obj, dfs_dir_anchor_t **_anchor)
+{
+	dfs_dir_anchor_t *anchor;
+
+	if (obj == NULL || !S_ISDIR(obj->mode))
+		return ENOTDIR;
+
+	D_ALLOC_PTR(anchor);
+	if (anchor == NULL)
+		return ENOMEM;
+
+	anchor->dda_dir = obj;
+	daos_anchor_init(&anchor->dda_anchor_int, 0);
+	anchor->dda_bucket_id     = 0;
+	anchor->dda_bucket_offset = 0;
+	*_anchor                  = anchor;
+	return 0;
+}
+
+void
+dfs_dir_anchor_reset(dfs_dir_anchor_t *anchor)
+{
+	daos_anchor_init(&anchor->dda_anchor_int, 0);
+	anchor->dda_bucket_id     = 0;
+	anchor->dda_bucket_offset = 0;
+}
+
+bool
+dfs_dir_anchor_is_eof(dfs_dir_anchor_t *anchor)
+{
+	return daos_anchor_is_eof(&anchor->dda_anchor_int);
+}
+
+void
+dfs_dir_anchor_destroy(dfs_dir_anchor_t *anchor)
+{
+	D_FREE(anchor);
+}
+
+int
+dfs_readdir_s(dfs_t *dfs, dfs_obj_t *dir, dfs_dir_anchor_t *anchor, struct dirent *entry)
+{
+	uint32_t nr = 1;
+	int      rc;
+
+	if (daos_oid_cmp(dir->oid, anchor->dda_dir->oid) != 0)
+		return EINVAL;
+	if (daos_anchor_is_eof(&anchor->dda_anchor_int))
+		return -1;
+
+	rc = readdir_int(dfs, dir, &anchor->dda_anchor_int, &nr, entry, NULL);
+	if (rc)
+		return rc;
+
+	/** if we did not enumerate anything, try again to make sure we hit EOF */
+	if (nr == 0) {
+		if (daos_anchor_is_eof(&anchor->dda_anchor_int))
+			return -1; /** typically EOF code */
+		else
+			return EIO;
+	}
+	return rc;
+#if 0
+	/** if no caching, just use the internal anchor with 1 entry */
+	if (dfs->dcache == NULL)
+		return readdir_int(dfs, obj, &anchor->dda_anchor_int, 1, &dir, NULL);
+	else
+		dcache_readdir(dfs->dcache, obj, anchor, dir);
+#endif
+}
+
 int
 dfs_iterate(dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr, size_t size,
 	    dfs_filler_cb_t op, void *udata)

src/include/daos_fs.h

@@ -1,5 +1,6 @@
 /*
  * (C) Copyright 2018-2024 Intel Corporation.
+ * (C) Copyright 2025 Hewlett Packard Enterprise Development LP
  *
  * SPDX-License-Identifier: BSD-2-Clause-Patent
  */
@@ -47,6 +48,8 @@ extern "C" {
 typedef struct dfs_obj dfs_obj_t;
 /** DFS mount handle struct */
 typedef struct dfs dfs_t;
+/** DFS readdir anchor for dfs_readdir_s() */
+typedef struct dfs_dir_anchor dfs_dir_anchor_t;
 
 /*
  * Consistency modes of the DFS container. A container created with balanced
@@ -741,6 +744,76 @@ int
 dfs_readdirplus(dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr,
 		struct dirent *dirs, struct stat *stbufs);
 
+/**
+ * Initialize a readdir anchor for dfs_readdir_s().
+ *
+ * \param[in]   dir     Opened directory object for readdir.
+ * \param[out]	anchor	Pointer to initialized anchor. This muse be freed with
+ *			dfs_dir_anchor_destroy().
+ *
+ * \return              0 on success, errno code on failure.
+ */
+int
+dfs_dir_anchor_init(dfs_obj_t *dir, dfs_dir_anchor_t **anchor);
+
+/**
+ * Reset an anchor the beginning of dir stream.
+ *
+ * \param[in]  anchor  anchor to reset
+ *
+ */
+void
+dfs_dir_anchor_reset(dfs_dir_anchor_t *anchor);
+
+/**
+ * check if the anchor is at EOF.
+ *
+ * \param[in]	anchor	anchor to check
+ *
+ * \return		true if anchor is at EOF, false otherwise.
+ */
+bool
+dfs_dir_anchor_is_eof(dfs_dir_anchor_t *anchor);
+
+/**
+ * Destroy/free a DFS readdir anchor.
+ *
+ * \param[in]  anchor  anchor to free
+ *
+ */
+void
+dfs_dir_anchor_destroy(dfs_dir_anchor_t *anchor);
+
+/**
+ * Directory readdir that just returns the next entry in the directory anchor stream. The stream is
+ * actually determined by the anchor which can be reset at anytime to start from the beginning. For
+ * every call of this function with the anchor, it returns 0 with the d_name of the dirent struct
+ * populated for the next entry. The function returns -1 if it reaches the end of stream and sets
+ * anchor to EOF. It is possible to get the last entry in the stream and the anchor being set to EOF
+ * in that call. It is also possible to get the last entry in the stream and the anchor still not
+ * set to EOF in that readdir call. In both situations the return code of the readdir call is 0
+ * (success) and the entry is valid and should be consumed. In the latter case, the caller does not
+ * know that we reached the end of the directory and should make another readdir call. The next call
+ * in both scenarios will return -1 and the anchor will be set to EOF in that call. Further calls
+ * will behave similarly until the anchor is reset to the beginning.
+ *
+ * If caching is enabled on this dfs mount, this readdir call will utilize the readdir cache and may
+ * pull in an entire bucket of entries at once if the current stream is not in the cache.
+ *
+ * \param[in]	dfs	Pointer to the mounted file system.
+ * \param[in]	obj	Opened directory object.
+ * \param[in,out]
+ *		anchor	Anchor for the next call, it should initialized before first use.
+ * \param[out]	dir	returned dirent. Unlike the libc call, this dirent pointer is provided by
+ *			the caller and not an internal pointer.
+ *
+ * \return		0 on success
+ *			-1 on end of dir stream (no more entries to enumerate)
+ *			errno code on failure
+ */
+int
+dfs_readdir_s(dfs_t *dfs, dfs_obj_t *obj, dfs_dir_anchor_t *anchor, struct dirent *dir);
+
 /**
  * User callback defined for dfs_readdir_size.
  */