Logo ROOT  
Reference Guide
RDaos.hxx
Go to the documentation of this file.
1/// \file ROOT/RDaos.hxx
2/// \ingroup NTuple ROOT7
3/// \author Javier Lopez-Gomez <j.lopez@cern.ch>
4/// \date 2020-11-14
5/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
6/// is welcome!
7
8/*************************************************************************
9 * Copyright (C) 1995-2021, Rene Brun and Fons Rademakers. *
10 * All rights reserved. *
11 * *
12 * For the licensing terms see $ROOTSYS/LICENSE. *
13 * For the list of contributors see $ROOTSYS/README/CREDITS. *
14 *************************************************************************/
15
16#ifndef ROOT7_RDaos
17#define ROOT7_RDaos
18
19#include <ROOT/RStringView.hxx>
20#include <ROOT/TypeTraits.hxx>
21
22#include <daos.h>
23// Avoid depending on `gurt/common.h` as the only required declaration is `d_rank_list_free()`.
24// Also, this header file is known to provide macros that conflict with std::min()/std::max().
25extern "C" void d_rank_list_free(d_rank_list_t *rank_list);
26
27#include <functional>
28#include <memory>
29#include <string>
30#include <type_traits>
31#include <vector>
32
33namespace ROOT {
34
35namespace Experimental {
36namespace Detail {
37class RDaosContainer;
38
39/**
40 \class RDaosPool
41 \brief A RDaosPool provides access to containers in a specific DAOS pool.
42 */
43class RDaosPool {
44 friend class RDaosContainer;
45private:
47 uuid_t fPoolUuid{};
48
49public:
50 RDaosPool(const RDaosPool&) = delete;
51 RDaosPool(std::string_view poolUuid, std::string_view serviceReplicas);
52 ~RDaosPool();
53
54 RDaosPool& operator=(const RDaosPool&) = delete;
55};
56
57/**
58 \class RDaosObject
59 \brief Provides low-level access to DAOS objects in a container.
60 */
62private:
64public:
65 using DistributionKey_t = std::uint64_t;
66 using AttributeKey_t = std::uint64_t;
67
68 /// \brief Wrap around a `daos_oclass_id_t`. An object class describes the schema of data distribution
69 /// and protection.
70 struct ObjClassId {
72
73 ObjClassId(const ObjClassId&) = default;
75 ObjClassId(const std::string &name) : fCid(daos_oclass_name2id(name.data())) {}
76
77 bool IsUnknown() const { return fCid == OC_UNKNOWN; }
78 std::string ToString() const;
79
80 /// This limit is currently not defined in any header and any call to
81 /// `daos_oclass_id2name()` within DAOS uses a stack-allocated buffer
82 /// whose length varies from 16 to 50, e.g. `https://github.com/daos-stack/daos/blob/master/src/utils/daos_dfs_hdlr.c#L78`.
83 /// As discussed with the development team, 64 is a reasonable limit.
84 static constexpr std::size_t kOCNameMaxLength = 64;
85 };
86
87 /// \brief Contains required information for a single fetch/update operation.
89 FetchUpdateArgs() = default;
92 FetchUpdateArgs(DistributionKey_t &d, AttributeKey_t &a, std::vector<d_iov_t> &v, daos_event_t *p = nullptr);
94
95 /// \brief A `daos_key_t` is a type alias of `d_iov_t`. This type stores a pointer and a length.
96 /// In order for `fDistributionKey` and `fIods` to point to memory that we own, `fDkey` and
97 /// `fAkey` store a copy of the distribution and attribute key, respectively.
100
101 /// \brief The distribution key, as used by the `daos_obj_{fetch,update}` functions.
105 std::vector<d_iov_t> fIovs{};
106 daos_event_t *fEv = nullptr;
107 };
108
109 RDaosObject() = delete;
110 /// Provides low-level access to an object. If `cid` is OC_UNKNOWN, the user is responsible for
111 /// calling `daos_obj_generate_id()` to fill the reserved bits in `oid` before calling this constructor.
113 ~RDaosObject();
114
115 int Fetch(FetchUpdateArgs &args);
116 int Update(FetchUpdateArgs &args);
117};
118
119/**
120 \class RDaosContainer
121 \brief A RDaosContainer provides read/write access to objects in a given container.
122 */
124 friend class RDaosObject;
125public:
129
130 /// \brief Describes a read/write operation on multiple objects; see the `ReadV`/`WriteV` functions.
131 struct RWOperation {
132 RWOperation() = default;
138 std::vector<d_iov_t> fIovs{};
139 };
140
141private:
143 std::size_t fSize;
144 std::unique_ptr<daos_event_t[]> fEvs;
146 DaosEventQueue(std::size_t size);
148 /**
149 \brief Wait for all events in this event queue to complete.
150 \return Number of events still in the queue. This should be 0 on success.
151 */
152 int Poll();
153 };
154
157 std::shared_ptr<RDaosPool> fPool;
159
160 /**
161 \brief Perform a vector read/write operation on different objects.
162 \param vec A `std::vector<RWOperation>` that describes read/write operations to perform.
163 \param cid The `daos_oclass_id_t` used to qualify OIDs.
164 \param fn Either `std::mem_fn<&RDaosObject::Fetch>` (read) or `std::mem_fn<&RDaosObject::Update>` (write).
165 \return Number of requests that did not complete; this should be 0 after a successful call.
166 */
167 template <typename Fn>
168 int VectorReadWrite(std::vector<RWOperation> &vec, ObjClassId_t cid, Fn fn) {
169 int ret;
170 DaosEventQueue eventQueue(vec.size());
171 {
172 std::vector<std::tuple<std::unique_ptr<RDaosObject>, RDaosObject::FetchUpdateArgs>> requests{};
173 requests.reserve(vec.size());
174 for (size_t i = 0; i < vec.size(); ++i) {
175 requests.push_back(std::make_tuple(std::unique_ptr<RDaosObject>(new RDaosObject(*this, vec[i].fOid, cid.fCid)),
177 vec[i].fDistributionKey, vec[i].fAttributeKey,
178 vec[i].fIovs, &eventQueue.fEvs[i]}));
179 fn(std::get<0>(requests.back()).get(), std::get<1>(requests.back()));
180 }
181 ret = eventQueue.Poll();
182 }
183 return ret;
184 }
185
186public:
187 RDaosContainer(std::shared_ptr<RDaosPool> pool, std::string_view containerUuid, bool create = false);
189
192
193 /**
194 \brief Read data from a single object attribute key to the given buffer.
195 \param buffer The address of a buffer that has capacity for at least `length` bytes.
196 \param length Length of the buffer.
197 \param oid A 128-bit DAOS object identifier.
198 \param dkey The distribution key used for this operation.
199 \param akey The attribute key used for this operation.
200 \param cid An object class ID.
201 \return 0 if the operation succeeded; a negative DAOS error number otherwise.
202 */
203 int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid,
205 int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid,
207 { return ReadSingleAkey(buffer, length, oid, dkey, akey, fDefaultObjectClass); }
208
209 /**
210 \brief Write the given buffer to a single object attribute key.
211 \param buffer The address of the source buffer.
212 \param length Length of the buffer.
213 \param oid A 128-bit DAOS object identifier.
214 \param dkey The distribution key used for this operation.
215 \param akey The attribute key used for this operation.
216 \param cid An object class ID.
217 \return 0 if the operation succeeded; a negative DAOS error number otherwise.
218 */
219 int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid,
221 int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid,
223 { return WriteSingleAkey(buffer, length, oid, dkey, akey, fDefaultObjectClass); }
224
225 /**
226 \brief Perform a vector read operation on (possibly) multiple objects.
227 \param vec A `std::vector<RWOperation>` that describes read operations to perform.
228 \param cid An object class ID.
229 \return Number of operations that could not complete.
230 */
231 int ReadV(std::vector<RWOperation> &vec, ObjClassId_t cid)
232 { return VectorReadWrite(vec, cid, std::mem_fn(&RDaosObject::Fetch)); }
233 int ReadV(std::vector<RWOperation> &vec) { return ReadV(vec, fDefaultObjectClass); }
234
235 /**
236 \brief Perform a vector write operation on (possibly) multiple objects.
237 \param vec A `std::vector<RWOperation>` that describes write operations to perform.
238 \param cid An object class ID.
239 \return Number of operations that could not complete.
240 */
241 int WriteV(std::vector<RWOperation> &vec, ObjClassId_t cid)
242 { return VectorReadWrite(vec, cid, std::mem_fn(&RDaosObject::Update)); }
243 int WriteV(std::vector<RWOperation> &vec) { return WriteV(vec, fDefaultObjectClass); }
244};
245
246} // namespace Detail
247
248} // namespace Experimental
249} // namespace ROOT
250
251#endif
void d_rank_list_free(d_rank_list_t *rank_list)
#define d(i)
Definition: RSha256.hxx:102
size_t size(const MatrixT &matrix)
retrieve the size of a square matrix
char name[80]
Definition: TGX11.cxx:110
A RDaosContainer provides read/write access to objects in a given container.
Definition: RDaos.hxx:123
void SetDefaultObjectClass(const ObjClassId_t cid)
Definition: RDaos.hxx:191
std::shared_ptr< RDaosPool > fPool
Definition: RDaos.hxx:157
ObjClassId_t GetDefaultObjectClass() const
Definition: RDaos.hxx:190
int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey)
Definition: RDaos.hxx:221
int ReadV(std::vector< RWOperation > &vec)
Definition: RDaos.hxx:233
int WriteV(std::vector< RWOperation > &vec)
Definition: RDaos.hxx:243
int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey, ObjClassId_t cid)
Read data from a single object attribute key to the given buffer.
Definition: RDaos.cxx:166
RDaosObject::ObjClassId ObjClassId_t
Definition: RDaos.hxx:128
RDaosObject::DistributionKey_t DistributionKey_t
Definition: RDaos.hxx:126
int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey)
Definition: RDaos.hxx:205
RDaosObject::AttributeKey_t AttributeKey_t
Definition: RDaos.hxx:127
int WriteV(std::vector< RWOperation > &vec, ObjClassId_t cid)
Perform a vector write operation on (possibly) multiple objects.
Definition: RDaos.hxx:241
int ReadV(std::vector< RWOperation > &vec, ObjClassId_t cid)
Perform a vector read operation on (possibly) multiple objects.
Definition: RDaos.hxx:231
int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey, ObjClassId_t cid)
Write the given buffer to a single object attribute key.
Definition: RDaos.cxx:176
int VectorReadWrite(std::vector< RWOperation > &vec, ObjClassId_t cid, Fn fn)
Perform a vector read/write operation on different objects.
Definition: RDaos.hxx:168
RDaosContainer(std::shared_ptr< RDaosPool > pool, std::string_view containerUuid, bool create=false)
Definition: RDaos.cxx:146
Provides low-level access to DAOS objects in a container.
Definition: RDaos.hxx:61
int Update(FetchUpdateArgs &args)
Definition: RDaos.cxx:106
int Fetch(FetchUpdateArgs &args)
Definition: RDaos.cxx:98
A RDaosPool provides access to containers in a specific DAOS pool.
Definition: RDaos.hxx:43
RDaosPool & operator=(const RDaosPool &)=delete
RDaosPool(const RDaosPool &)=delete
This file is a reduced version of daos_xxx.h headers that provides (simplified) declarations for use ...
int daos_oclass_name2id(const char *name)
uint16_t daos_oclass_id_t
Definition: daos.h:133
@ OC_SX
Definition: daos.h:127
@ OC_UNKNOWN
Definition: daos.h:107
basic_string_view< char > string_view
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
int Poll()
Wait for all events in this event queue to complete.
Definition: RDaos.cxx:130
Describes a read/write operation on multiple objects; see the ReadV/WriteV functions.
Definition: RDaos.hxx:131
RWOperation(daos_obj_id_t o, DistributionKey_t d, AttributeKey_t a, std::vector< d_iov_t > &v)
Definition: RDaos.hxx:133
Contains required information for a single fetch/update operation.
Definition: RDaos.hxx:88
FetchUpdateArgs & operator=(const FetchUpdateArgs &)=delete
DistributionKey_t fDkey
A daos_key_t is a type alias of d_iov_t.
Definition: RDaos.hxx:98
daos_key_t fDistributionKey
The distribution key, as used by the daos_obj_{fetch,update} functions.
Definition: RDaos.hxx:102
Wrap around a daos_oclass_id_t.
Definition: RDaos.hxx:70
static constexpr std::size_t kOCNameMaxLength
This limit is currently not defined in any header and any call to daos_oclass_id2name() within DAOS u...
Definition: RDaos.hxx:84
iovec for memory buffer
Definition: daos.h:37
Scatter/gather list for memory buffers.
Definition: daos.h:48
Event and event queue.
Definition: daos.h:77
Generic handle for various DAOS components like container, object, etc.
Definition: daos.h:63
Definition: civetweb.c:2228
auto * a
Definition: textangle.C:12