openPMD-api
IOTask.hpp
1 /* Copyright 2017-2021 Fabian Koller
2  *
3  * This file is part of openPMD-api.
4  *
5  * openPMD-api is free software: you can redistribute it and/or modify
6  * it under the terms of of either the GNU General Public License or
7  * the GNU Lesser General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * openPMD-api is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License and the GNU Lesser General Public License
15  * for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * and the GNU Lesser General Public License along with openPMD-api.
19  * If not, see <http://www.gnu.org/licenses/>.
20  */
21 #pragma once
22 
23 #include "openPMD/ChunkInfo.hpp"
24 #include "openPMD/Dataset.hpp"
25 #include "openPMD/IterationEncoding.hpp"
26 #include "openPMD/Streaming.hpp"
27 #include "openPMD/auxiliary/Export.hpp"
28 #include "openPMD/auxiliary/Variant.hpp"
29 #include "openPMD/backend/Attribute.hpp"
30 
31 #include <map>
32 #include <memory>
33 #include <string>
34 #include <utility>
35 #include <vector>
36 
37 namespace openPMD
38 {
39 class AttributableInterface;
40 class Writable;
41 
42 Writable *getWritable(AttributableInterface *);
43 
47  CREATE_FILE, OPEN_FILE, CLOSE_FILE, DELETE_FILE,
48 
49  CREATE_PATH, CLOSE_PATH, OPEN_PATH, DELETE_PATH,
50  LIST_PATHS,
51 
52  CREATE_DATASET, EXTEND_DATASET, OPEN_DATASET, DELETE_DATASET,
53  WRITE_DATASET, READ_DATASET, LIST_DATASETS, GET_BUFFER_VIEW,
54 
55  DELETE_ATT, WRITE_ATT, READ_ATT, LIST_ATTS,
56 
57  ADVANCE,
58  AVAILABLE_CHUNKS
59 }; // note: if you change the enum members here, please update
60  // docs/source/dev/design.rst
61 
62 namespace internal
63 {
64  /*
65  * The returned strings are compile-time constants, so no worries about
66  * pointer validity.
67  */
68  std::string operationAsString(Operation);
69 } // namespace internal
70 
71 struct OPENPMDAPI_EXPORT AbstractParameter
72 {
73  virtual ~AbstractParameter() = default;
74  AbstractParameter() = default;
75  // AbstractParameter(AbstractParameter&&) = default;
76 
77  // avoid object slicing
78  AbstractParameter(const AbstractParameter &) = delete;
79  AbstractParameter &operator=(const AbstractParameter &) = delete;
80  virtual std::unique_ptr<AbstractParameter> clone() const = 0;
81 };
82 
92 template <Operation>
93 struct OPENPMDAPI_EXPORT Parameter : public AbstractParameter
94 {
95  Parameter() = delete;
96  Parameter(Parameter const &) = delete;
97  Parameter(Parameter &&) = delete;
98 };
99 
100 template <>
101 struct OPENPMDAPI_EXPORT Parameter<Operation::CREATE_FILE>
102  : public AbstractParameter
103 {
104  Parameter() = default;
105  Parameter(Parameter const &p)
106  : AbstractParameter(), name(p.name), encoding(p.encoding)
107  {}
108 
109  std::unique_ptr<AbstractParameter> clone() const override
110  {
111  return std::unique_ptr<AbstractParameter>(
113  }
114 
115  std::string name = "";
116  IterationEncoding encoding = IterationEncoding::groupBased;
117 };
118 
119 template <>
120 struct OPENPMDAPI_EXPORT Parameter<Operation::OPEN_FILE>
121  : public AbstractParameter
122 {
123  Parameter() = default;
124  Parameter(Parameter const &p)
125  : AbstractParameter(), name(p.name), encoding(p.encoding)
126  {}
127 
128  std::unique_ptr<AbstractParameter> clone() const override
129  {
130  return std::unique_ptr<AbstractParameter>(
132  }
133 
134  std::string name = "";
135  /*
136  * The backends might need to ensure availability of certain features
137  * for some iteration encodings, e.g. availability of ADIOS steps for
138  * variableBased encoding.
139  */
140  IterationEncoding encoding = IterationEncoding::groupBased;
141 };
142 
143 template <>
144 struct OPENPMDAPI_EXPORT Parameter<Operation::CLOSE_FILE>
145  : public AbstractParameter
146 {
147  Parameter() = default;
149  {}
150 
151  std::unique_ptr<AbstractParameter> clone() const override
152  {
153  return std::unique_ptr<AbstractParameter>(
155  }
156 };
157 
158 template <>
159 struct OPENPMDAPI_EXPORT Parameter<Operation::DELETE_FILE>
160  : public AbstractParameter
161 {
162  Parameter() = default;
163  Parameter(Parameter const &p) : AbstractParameter(), name(p.name)
164  {}
165 
166  std::unique_ptr<AbstractParameter> clone() const override
167  {
168  return std::unique_ptr<AbstractParameter>(
170  }
171 
172  std::string name = "";
173 };
174 
175 template <>
176 struct OPENPMDAPI_EXPORT Parameter<Operation::CREATE_PATH>
177  : public AbstractParameter
178 {
179  Parameter() = default;
180  Parameter(Parameter const &p) : AbstractParameter(), path(p.path)
181  {}
182 
183  std::unique_ptr<AbstractParameter> clone() const override
184  {
185  return std::unique_ptr<AbstractParameter>(
187  }
188 
189  std::string path = "";
190 };
191 
192 template <>
193 struct OPENPMDAPI_EXPORT Parameter<Operation::CLOSE_PATH>
194  : public AbstractParameter
195 {
196  Parameter() = default;
198  {}
199 
200  Parameter &operator=(Parameter const &)
201  {
202  return *this;
203  }
204 
205  std::unique_ptr<AbstractParameter> clone() const override
206  {
207  return std::unique_ptr<AbstractParameter>(
209  }
210 };
211 
212 template <>
213 struct OPENPMDAPI_EXPORT Parameter<Operation::OPEN_PATH>
214  : public AbstractParameter
215 {
216  Parameter() = default;
217  Parameter(Parameter const &p) : AbstractParameter(), path(p.path)
218  {}
219 
220  std::unique_ptr<AbstractParameter> clone() const override
221  {
222  return std::unique_ptr<AbstractParameter>(
224  }
225 
226  std::string path = "";
227 };
228 
229 template <>
230 struct OPENPMDAPI_EXPORT Parameter<Operation::DELETE_PATH>
231  : public AbstractParameter
232 {
233  Parameter() = default;
234  Parameter(Parameter const &p) : AbstractParameter(), path(p.path)
235  {}
236 
237  std::unique_ptr<AbstractParameter> clone() const override
238  {
239  return std::unique_ptr<AbstractParameter>(
241  }
242 
243  std::string path = "";
244 };
245 
246 template <>
247 struct OPENPMDAPI_EXPORT Parameter<Operation::LIST_PATHS>
248  : public AbstractParameter
249 {
250  Parameter() = default;
251  Parameter(Parameter const &p) : AbstractParameter(), paths(p.paths)
252  {}
253 
254  std::unique_ptr<AbstractParameter> clone() const override
255  {
256  return std::unique_ptr<AbstractParameter>(
258  }
259 
260  std::shared_ptr<std::vector<std::string> > paths =
261  std::make_shared<std::vector<std::string> >();
262 };
263 
264 template <>
265 struct OPENPMDAPI_EXPORT Parameter<Operation::CREATE_DATASET>
266  : public AbstractParameter
267 {
268  Parameter() = default;
269  Parameter(Parameter const &p)
271  , name(p.name)
272  , extent(p.extent)
273  , dtype(p.dtype)
274  , chunkSize(p.chunkSize)
275  , compression(p.compression)
276  , transform(p.transform)
277  , options(p.options)
278  {}
279 
280  std::unique_ptr<AbstractParameter> clone() const override
281  {
282  return std::unique_ptr<AbstractParameter>(
284  }
285 
286  std::string name = "";
287  Extent extent = {};
288  Datatype dtype = Datatype::UNDEFINED;
289  Extent chunkSize = {};
290  std::string compression = "";
291  std::string transform = "";
292  std::string options = "{}";
293 };
294 
295 template <>
296 struct OPENPMDAPI_EXPORT Parameter<Operation::EXTEND_DATASET>
297  : public AbstractParameter
298 {
299  Parameter() = default;
300  Parameter(Parameter const &p) : AbstractParameter(), extent(p.extent)
301  {}
302 
303  std::unique_ptr<AbstractParameter> clone() const override
304  {
305  return std::unique_ptr<AbstractParameter>(
307  }
308 
309  Extent extent = {};
310 };
311 
312 template <>
313 struct OPENPMDAPI_EXPORT Parameter<Operation::OPEN_DATASET>
314  : public AbstractParameter
315 {
316  Parameter() = default;
317  Parameter(Parameter const &p)
318  : AbstractParameter(), name(p.name), dtype(p.dtype), extent(p.extent)
319  {}
320 
321  std::unique_ptr<AbstractParameter> clone() const override
322  {
323  return std::unique_ptr<AbstractParameter>(
325  }
326 
327  std::string name = "";
328  std::shared_ptr<Datatype> dtype = std::make_shared<Datatype>();
329  std::shared_ptr<Extent> extent = std::make_shared<Extent>();
330 };
331 
332 template <>
333 struct OPENPMDAPI_EXPORT Parameter<Operation::DELETE_DATASET>
334  : public AbstractParameter
335 {
336  Parameter() = default;
337  Parameter(Parameter const &p) : AbstractParameter(), name(p.name)
338  {}
339 
340  std::unique_ptr<AbstractParameter> clone() const override
341  {
342  return std::unique_ptr<AbstractParameter>(
344  }
345 
346  std::string name = "";
347 };
348 
349 template <>
350 struct OPENPMDAPI_EXPORT Parameter<Operation::WRITE_DATASET>
351  : public AbstractParameter
352 {
353  Parameter() = default;
356  , extent(p.extent)
357  , offset(p.offset)
358  , dtype(p.dtype)
359  , data(p.data)
360  {}
361 
362  Parameter &operator=(const Parameter &p)
363  {
364  this->extent = p.extent;
365  this->offset = p.offset;
366  this->dtype = p.dtype;
367  this->data = p.data;
368  return *this;
369  }
370 
371  std::unique_ptr<AbstractParameter> clone() const override
372  {
373  return std::unique_ptr<AbstractParameter>(
375  }
376 
377  Extent extent = {};
378  Offset offset = {};
379  Datatype dtype = Datatype::UNDEFINED;
380  std::shared_ptr<void const> data = nullptr;
381 };
382 
383 template <>
384 struct OPENPMDAPI_EXPORT Parameter<Operation::READ_DATASET>
385  : public AbstractParameter
386 {
387  Parameter() = default;
390  , extent(p.extent)
391  , offset(p.offset)
392  , dtype(p.dtype)
393  , data(p.data)
394  {}
395 
396  Parameter &operator=(const Parameter &p)
397  {
398  this->extent = p.extent;
399  this->offset = p.offset;
400  this->dtype = p.dtype;
401  this->data = p.data;
402  return *this;
403  }
404 
405  std::unique_ptr<AbstractParameter> clone() const override
406  {
407  return std::unique_ptr<AbstractParameter>(
409  }
410 
411  Extent extent = {};
412  Offset offset = {};
413  Datatype dtype = Datatype::UNDEFINED;
414  std::shared_ptr<void> data = nullptr;
415 };
416 
417 template <>
418 struct OPENPMDAPI_EXPORT Parameter<Operation::LIST_DATASETS>
419  : public AbstractParameter
420 {
421  Parameter() = default;
422  Parameter(Parameter const &p) : AbstractParameter(), datasets(p.datasets)
423  {}
424 
425  std::unique_ptr<AbstractParameter> clone() const override
426  {
427  return std::unique_ptr<AbstractParameter>(
429  }
430 
431  std::shared_ptr<std::vector<std::string> > datasets =
432  std::make_shared<std::vector<std::string> >();
433 };
434 
435 template <>
436 struct OPENPMDAPI_EXPORT Parameter<Operation::GET_BUFFER_VIEW>
437  : public AbstractParameter
438 {
439  Parameter() = default;
440  Parameter(Parameter const &p)
442  , offset(p.offset)
443  , extent(p.extent)
444  , dtype(p.dtype)
445  , update(p.update)
446  , out(p.out)
447  {}
448 
449  std::unique_ptr<AbstractParameter> clone() const override
450  {
451  return std::unique_ptr<AbstractParameter>(
453  }
454 
455  // in parameters
456  Offset offset;
457  Extent extent;
458  Datatype dtype = Datatype::UNDEFINED;
459  bool update = false;
460  // out parameters
461  struct OutParameters
462  {
463  bool backendManagedBuffer = false;
464  unsigned viewIndex = 0;
465  void *ptr = nullptr;
466  };
467  std::shared_ptr<OutParameters> out = std::make_shared<OutParameters>();
468 };
469 
470 template <>
471 struct OPENPMDAPI_EXPORT Parameter<Operation::DELETE_ATT>
472  : public AbstractParameter
473 {
474  Parameter() = default;
475  Parameter(Parameter const &p) : AbstractParameter(), name(p.name)
476  {}
477 
478  std::unique_ptr<AbstractParameter> clone() const override
479  {
480  return std::unique_ptr<AbstractParameter>(
482  }
483 
484  std::string name = "";
485 };
486 
487 template <>
488 struct OPENPMDAPI_EXPORT Parameter<Operation::WRITE_ATT>
489  : public AbstractParameter
490 {
491  Parameter() = default;
492  Parameter(Parameter const &p)
494  , name(p.name)
495  , dtype(p.dtype)
496  , resource(p.resource)
497  {}
498 
499  std::unique_ptr<AbstractParameter> clone() const override
500  {
501  return std::unique_ptr<AbstractParameter>(
503  }
504 
505  std::string name = "";
506  Datatype dtype = Datatype::UNDEFINED;
507  Attribute::resource resource;
508 };
509 
510 template <>
511 struct OPENPMDAPI_EXPORT Parameter<Operation::READ_ATT>
512  : public AbstractParameter
513 {
514  Parameter() = default;
515  Parameter(Parameter const &p)
517  , name(p.name)
518  , dtype(p.dtype)
519  , resource(p.resource)
520  {}
521 
522  Parameter &operator=(const Parameter &p)
523  {
524  this->name = p.name;
525  this->dtype = p.dtype;
526  this->resource = p.resource;
527  return *this;
528  }
529 
530  std::unique_ptr<AbstractParameter> clone() const override
531  {
532  return std::unique_ptr<AbstractParameter>(
533  new Parameter<Operation::READ_ATT>(*this));
534  }
535 
536  std::string name = "";
537  std::shared_ptr<Datatype> dtype = std::make_shared<Datatype>();
538  std::shared_ptr<Attribute::resource> resource =
539  std::make_shared<Attribute::resource>();
540 };
541 
542 template <>
543 struct OPENPMDAPI_EXPORT Parameter<Operation::LIST_ATTS>
544  : public AbstractParameter
545 {
546  Parameter() = default;
547  Parameter(Parameter const &p)
548  : AbstractParameter(), attributes(p.attributes)
549  {}
550 
551  std::unique_ptr<AbstractParameter> clone() const override
552  {
553  return std::unique_ptr<AbstractParameter>(
555  }
556 
557  std::shared_ptr<std::vector<std::string> > attributes =
558  std::make_shared<std::vector<std::string> >();
559 };
560 
561 template <>
562 struct OPENPMDAPI_EXPORT Parameter<Operation::ADVANCE>
563  : public AbstractParameter
564 {
565  Parameter() = default;
566  Parameter(Parameter const &p)
567  : AbstractParameter(), mode(p.mode), status(p.status)
568  {}
569 
570  std::unique_ptr<AbstractParameter> clone() const override
571  {
572  return std::unique_ptr<AbstractParameter>(
573  new Parameter<Operation::ADVANCE>(*this));
574  }
575 
579  std::shared_ptr<AdvanceStatus> status =
580  std::make_shared<AdvanceStatus>(AdvanceStatus::OK);
581 };
582 
583 template <>
584 struct OPENPMDAPI_EXPORT Parameter<Operation::AVAILABLE_CHUNKS>
585  : public AbstractParameter
586 {
587  Parameter() = default;
588  Parameter(Parameter const &p) : AbstractParameter(), chunks(p.chunks)
589  {}
590 
591  Parameter &operator=(Parameter const &p)
592  {
593  chunks = p.chunks;
594  return *this;
595  }
596 
597  std::unique_ptr<AbstractParameter> clone() const override
598  {
599  return std::unique_ptr<AbstractParameter>(
601  }
602 
603  // output parameter
604  std::shared_ptr<ChunkTable> chunks = std::make_shared<ChunkTable>();
605 };
606 
615 class OPENPMDAPI_EXPORT IOTask
616 {
617 public:
626  template <Operation op>
627  explicit IOTask(Writable *w, Parameter<op> const &p)
628  : writable{w}, operation{op}, parameter{p.clone()}
629  {}
630 
631  template <Operation op>
632  explicit IOTask(AttributableInterface *a, Parameter<op> const &p)
633  : writable{getWritable(a)}, operation{op}, parameter{p.clone()}
634  {}
635 
636  explicit IOTask(IOTask const &other)
637  : writable{other.writable}
638  , operation{other.operation}
639  , parameter{other.parameter}
640  {}
641 
642  IOTask &operator=(IOTask const &other)
643  {
644  writable = other.writable;
645  operation = other.operation;
646  parameter = other.parameter;
647  return *this;
648  }
649 
650  Writable *writable;
651  Operation operation;
652  std::shared_ptr<AbstractParameter> parameter;
653 }; // IOTask
654 } // namespace openPMD
Self-contained description of a single IO operation.
Definition: IOTask.hpp:615
AdvanceMode mode
input parameter
Definition: IOTask.hpp:577
AdvanceMode
In step-based mode (i.e.
Definition: Streaming.hpp:33
Datatype
Concrete datatype of an object available at runtime.
Definition: Datatype.hpp:45
Public definitions of openPMD-api.
Definition: Date.cpp:28
Layer to mirror structure of logical data and persistent data in file.
Definition: Writable.hpp:63
Typesafe description of all required arguments for a specified Operation.
Definition: IOTask.hpp:93
OPENPMDAPI_EXPORT_ENUM_CLASS(Operation)
Type of IO operation between logical and persistent data.
Definition: IOTask.hpp:46
Layer to manage storage of attributes associated with file objects.
Definition: Attributable.hpp:128
Definition: IOTask.hpp:71
IterationEncoding
Encoding scheme of an Iterations Series&#39;.
Definition: IterationEncoding.hpp:32
IOTask(Writable *w, Parameter< op > const &p)
Constructor for self-contained description of single IO operation.
Definition: IOTask.hpp:627