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#include <ROOT/RSpan.hxx>
22
23#include <daos.h>
24
25#include <functional>
26#include <memory>
27#include <string>
28#include <type_traits>
29#include <vector>
30#include <optional>
31#include <unordered_map>
32
33#ifndef DAOS_UUID_STR_SIZE
34#define DAOS_UUID_STR_SIZE 37
35#endif
36
37namespace ROOT {
38
39namespace Experimental {
40namespace Detail {
41
46
47 /// \brief Sets event barrier for a given parent event and waits for the completion of all children launched before
48 /// the barrier (must have at least one child).
49 /// \return 0 on success; a DAOS error code otherwise (< 0).
51 /// \brief Reserve event in queue, optionally tied to a parent event.
52 /// \return 0 on success; a DAOS error code otherwise (< 0).
53 int InitializeEvent(daos_event_t *ev_ptr, daos_event_t *parent_ptr = nullptr);
54 /// \brief Release event data from queue.
55 /// \return 0 on success; a DAOS error code otherwise (< 0).
56 int FinalizeEvent(daos_event_t *ev_ptr);
57};
58
59class RDaosContainer;
60
61/**
62 \class RDaosPool
63 \brief A RDaosPool provides access to containers in a specific DAOS pool.
64 */
65class RDaosPool {
66 friend class RDaosContainer;
67private:
69 uuid_t fPoolUuid{};
70 std::string fPoolLabel{};
71 std::unique_ptr<RDaosEventQueue> fEventQueue;
72
73public:
74 RDaosPool(const RDaosPool&) = delete;
76 ~RDaosPool();
77
78 RDaosPool& operator=(const RDaosPool&) = delete;
79 std::string GetPoolUuid();
80};
81
82/**
83 \class RDaosObject
84 \brief Provides low-level access to DAOS objects in a container.
85 */
87private:
89public:
90 using DistributionKey_t = std::uint64_t;
91 using AttributeKey_t = std::uint64_t;
92 /// \brief Wrap around a `daos_oclass_id_t`. An object class describes the schema of data distribution
93 /// and protection.
94 struct ObjClassId {
96
98 ObjClassId(const std::string &name) : fCid(daos_oclass_name2id(name.data())) {}
99
100 bool IsUnknown() const { return fCid == OC_UNKNOWN; }
101 std::string ToString() const;
102
103 /// This limit is currently not defined in any header and any call to
104 /// `daos_oclass_id2name()` within DAOS uses a stack-allocated buffer
105 /// whose length varies from 16 to 50, e.g. `https://github.com/daos-stack/daos/blob/master/src/utils/daos_dfs_hdlr.c#L78`.
106 /// As discussed with the development team, 64 is a reasonable limit.
107 static constexpr std::size_t kOCNameMaxLength = 64;
108 };
109
110 /// \brief Contains required information for a single fetch/update operation.
112 FetchUpdateArgs() = default;
115 FetchUpdateArgs(DistributionKey_t d, std::span<const AttributeKey_t> as, std::span<d_iov_t> vs,
116 bool is_async = false);
119
120 /// \brief A `daos_key_t` is a type alias of `d_iov_t`. This type stores a pointer and a length.
121 /// In order for `fDistributionKey` to point to memory that we own, `fDkey` holds the distribution key.
122 /// `fAkeys` and `fIovs` are sequential containers assumed to remain valid throughout the fetch/update operation.
124 std::span<const AttributeKey_t> fAkeys{};
125 std::span<d_iov_t> fIovs{};
126
127 /// \brief The distribution key, as used by the `daos_obj_{fetch,update}` functions.
129 std::vector<daos_iod_t> fIods{};
130 std::vector<d_sg_list_t> fSgls{};
131 std::optional<daos_event_t> fEvent{};
132 };
133
134 RDaosObject() = delete;
135 /// Provides low-level access to an object. If `cid` is OC_UNKNOWN, the user is responsible for
136 /// calling `daos_obj_generate_oid()` to fill the reserved bits in `oid` before calling this constructor.
138 ~RDaosObject();
139
140 int Fetch(FetchUpdateArgs &args);
141 int Update(FetchUpdateArgs &args);
142};
143
144/**
145 \class RDaosContainer
146 \brief A RDaosContainer provides read/write access to objects in a given container.
147 */
149 friend class RDaosObject;
150public:
154
155 /// \brief A pair of <object ID, distribution key> that can be used to issue a fetch/update request for multiple
156 /// attribute keys.
160 ROidDkeyPair() = default;
161
162 inline bool operator==(const ROidDkeyPair &other) const
163 {
164 return this->oid.lo == other.oid.lo && this->oid.hi == other.oid.hi && this->dkey == other.dkey;
165 }
166
167 struct Hash {
168 auto operator()(const ROidDkeyPair &x) const
169 {
170 /// Implementation borrowed from `boost::hash_combine`. Comparable to initial seeding with `oid.hi` followed
171 /// by two subsequent hash calls for `oid.lo` and `dkey`.
172 auto seed = std::hash<uint64_t>{}(x.oid.hi);
173 seed ^= std::hash<uint64_t>{}(x.oid.lo) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
174 seed ^= std::hash<DistributionKey_t>{}(x.dkey) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
175 return seed;
176 }
177 };
178 };
179
180 /// \brief Describes a read/write operation on multiple objects; see the `ReadV`/`WriteV` functions.
181 struct RWOperation {
182 RWOperation() = default;
183 RWOperation(daos_obj_id_t o, DistributionKey_t d, const std::vector<AttributeKey_t> &as,
184 const std::vector<d_iov_t> &vs)
189 std::vector<AttributeKey_t> fAttributeKeys{};
190 std::vector<d_iov_t> fIovs{};
191
193 {
194 fAttributeKeys.emplace_back(attr);
195 fIovs.emplace_back(vec);
196 }
197 };
198
199 using MultiObjectRWOperation_t = std::unordered_map<ROidDkeyPair, RWOperation, ROidDkeyPair::Hash>;
200
201 std::string GetContainerUuid();
202
203private:
206 std::string fContainerLabel{};
207 std::shared_ptr<RDaosPool> fPool;
209
210 /**
211 \brief Perform a vector read/write operation on different objects.
212 \param map A `MultiObjectRWOperation_t` that describes read/write operations to perform.
213 \param cid The `daos_oclass_id_t` used to qualify OIDs.
214 \param fn Either `&RDaosObject::Fetch` (read) or `&RDaosObject::Update` (write).
215 \return 0 if the operation succeeded; a negative DAOS error number otherwise.
216 */
219
220public:
221 RDaosContainer(std::shared_ptr<RDaosPool> pool, std::string_view containerId, bool create = false);
223
226
227 /**
228 \brief Read data from a single object attribute key to the given buffer.
229 \param buffer The address of a buffer that has capacity for at least `length` bytes.
230 \param length Length of the buffer.
231 \param oid A 128-bit DAOS object identifier.
232 \param dkey The distribution key used for this operation.
233 \param akey The attribute key used for this operation.
234 \param cid An object class ID.
235 \return 0 if the operation succeeded; a negative DAOS error number otherwise.
236 */
237 int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid,
239 int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid,
241 { return ReadSingleAkey(buffer, length, oid, dkey, akey, fDefaultObjectClass); }
242
243 /**
244 \brief Write the given buffer to a single object attribute key.
245 \param buffer The address of the source buffer.
246 \param length Length of the buffer.
247 \param oid A 128-bit DAOS object identifier.
248 \param dkey The distribution key used for this operation.
249 \param akey The attribute key used for this operation.
250 \param cid An object class ID.
251 \return 0 if the operation succeeded; a negative DAOS error number otherwise.
252 */
253 int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid,
255 int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid,
257 { return WriteSingleAkey(buffer, length, oid, dkey, akey, fDefaultObjectClass); }
258
259 /**
260 \brief Perform a vector read operation on multiple objects.
261 \param map A `MultiObjectRWOperation_t` that describes read operations to perform.
262 \param cid An object class ID.
263 \return Number of operations that could not complete.
264 */
267
268 /**
269 \brief Perform a vector write operation on multiple objects.
270 \param map A `MultiObjectRWOperation_t` that describes write operations to perform.
271 \param cid An object class ID.
272 \return Number of operations that could not complete.
273 */
275 {
276 return VectorReadWrite(map, cid, &RDaosObject::Update);
277 }
279};
280
281} // namespace Detail
282
283} // namespace Experimental
284} // namespace ROOT
285
286#endif
#define d(i)
Definition: RSha256.hxx:102
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void data
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h length
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t attr
char name[80]
Definition: TGX11.cxx:110
A RDaosContainer provides read/write access to objects in a given container.
Definition: RDaos.hxx:148
void SetDefaultObjectClass(const ObjClassId_t cid)
Definition: RDaos.hxx:225
std::shared_ptr< RDaosPool > fPool
Definition: RDaos.hxx:207
RDaosContainer(std::shared_ptr< RDaosPool > pool, std::string_view containerId, bool create=false)
Definition: RDaos.cxx:174
ObjClassId_t GetDefaultObjectClass() const
Definition: RDaos.hxx:224
int ReadV(MultiObjectRWOperation_t &map, ObjClassId_t cid)
Perform a vector read operation on multiple objects.
Definition: RDaos.hxx:265
int WriteSingleAkey(const void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey)
Definition: RDaos.hxx:255
std::unordered_map< ROidDkeyPair, RWOperation, ROidDkeyPair::Hash > MultiObjectRWOperation_t
Definition: RDaos.hxx:199
int ReadV(MultiObjectRWOperation_t &map)
Definition: RDaos.hxx:266
int WriteV(MultiObjectRWOperation_t &map, ObjClassId_t cid)
Perform a vector write operation on multiple objects.
Definition: RDaos.hxx:274
int WriteV(MultiObjectRWOperation_t &map)
Definition: RDaos.hxx:278
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:209
RDaosObject::ObjClassId ObjClassId_t
Definition: RDaos.hxx:153
RDaosObject::DistributionKey_t DistributionKey_t
Definition: RDaos.hxx:151
int ReadSingleAkey(void *buffer, std::size_t length, daos_obj_id_t oid, DistributionKey_t dkey, AttributeKey_t akey)
Definition: RDaos.hxx:239
RDaosObject::AttributeKey_t AttributeKey_t
Definition: RDaos.hxx:152
int VectorReadWrite(MultiObjectRWOperation_t &map, ObjClassId_t cid, int(RDaosObject::*fn)(RDaosObject::FetchUpdateArgs &))
Perform a vector read/write operation on different objects.
Definition: RDaos.cxx: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:220
Provides low-level access to DAOS objects in a container.
Definition: RDaos.hxx:86
int Update(FetchUpdateArgs &args)
Definition: RDaos.cxx:130
int Fetch(FetchUpdateArgs &args)
Definition: RDaos.cxx:123
A RDaosPool provides access to containers in a specific DAOS pool.
Definition: RDaos.hxx:65
RDaosPool & operator=(const RDaosPool &)=delete
std::unique_ptr< RDaosEventQueue > fEventQueue
Definition: RDaos.hxx:71
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:135
@ OC_SX
Definition: daos.h:129
@ OC_UNKNOWN
Definition: daos.h:109
Double_t x[n]
Definition: legend1.C:17
basic_string_view< char > string_view
This file contains a specialised ROOT message handler to test for diagnostic in unit tests.
TString as(SEXP s)
Definition: RExports.h:86
A pair of <object ID, distribution key> that can be used to issue a fetch/update request for multiple...
Definition: RDaos.hxx:157
bool operator==(const ROidDkeyPair &other) const
Definition: RDaos.hxx:162
Describes a read/write operation on multiple objects; see the ReadV/WriteV functions.
Definition: RDaos.hxx:181
std::vector< AttributeKey_t > fAttributeKeys
Definition: RDaos.hxx:189
RWOperation(daos_obj_id_t o, DistributionKey_t d, const std::vector< AttributeKey_t > &as, const std::vector< d_iov_t > &vs)
Definition: RDaos.hxx:183
void insert(AttributeKey_t attr, const d_iov_t &vec)
Definition: RDaos.hxx:192
int FinalizeEvent(daos_event_t *ev_ptr)
Release event data from queue.
Definition: RDaos.cxx:154
int InitializeEvent(daos_event_t *ev_ptr, daos_event_t *parent_ptr=nullptr)
Reserve event in queue, optionally tied to a parent event.
Definition: RDaos.cxx:149
int WaitOnParentBarrier(daos_event_t *ev_ptr)
Sets event barrier for a given parent event and waits for the completion of all children launched bef...
Definition: RDaos.cxx:159
Contains required information for a single fetch/update operation.
Definition: RDaos.hxx:111
FetchUpdateArgs & operator=(const FetchUpdateArgs &)=delete
DistributionKey_t fDkey
A daos_key_t is a type alias of d_iov_t.
Definition: RDaos.hxx:123
daos_key_t fDistributionKey
The distribution key, as used by the daos_obj_{fetch,update} functions.
Definition: RDaos.hxx:128
std::span< const AttributeKey_t > fAkeys
Definition: RDaos.hxx:124
Wrap around a daos_oclass_id_t.
Definition: RDaos.hxx:94
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:107
iovec for memory buffer
Definition: daos.h:37
Event and event queue.
Definition: daos.h:79
Generic handle for various DAOS components like container, object, etc.
Definition: daos.h:59
uint64_t hi
Definition: daos.h:147
uint64_t lo
Definition: daos.h:146
Definition: civetweb.c:1856