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/auxiliary/Export.hpp"
24 #include "openPMD/auxiliary/Variant.hpp"
25 #include "openPMD/backend/Attribute.hpp"
26 #include "openPMD/ChunkInfo.hpp"
27 #include "openPMD/Dataset.hpp"
28 #include "openPMD/IterationEncoding.hpp"
29 #include "openPMD/Streaming.hpp"
30 
31 #include <memory>
32 #include <map>
33 #include <string>
34 #include <utility>
35 #include <vector>
36 
37 
38 namespace openPMD
39 {
40 class AttributableInterface;
41 class Writable;
42 
43 Writable*
44 getWritable(AttributableInterface*);
45 
49 {
50  CREATE_FILE,
51  OPEN_FILE,
52  CLOSE_FILE,
53  DELETE_FILE,
54 
55  CREATE_PATH,
56  CLOSE_PATH,
57  OPEN_PATH,
58  DELETE_PATH,
59  LIST_PATHS,
60 
61  CREATE_DATASET,
62  EXTEND_DATASET,
63  OPEN_DATASET,
64  DELETE_DATASET,
65  WRITE_DATASET,
66  READ_DATASET,
67  LIST_DATASETS,
68  GET_BUFFER_VIEW,
69 
70  DELETE_ATT,
71  WRITE_ATT,
72  READ_ATT,
73  LIST_ATTS,
74 
75  ADVANCE,
76  AVAILABLE_CHUNKS
77 }; // note: if you change the enum members here, please update docs/source/dev/design.rst
78 
79 namespace internal
80 {
81  /*
82  * The returned strings are compile-time constants, so no worries about
83  * pointer validity.
84  */
85  std::string operationAsString( Operation );
86 }
87 
88 struct OPENPMDAPI_EXPORT AbstractParameter
89 {
90  virtual ~AbstractParameter() = default;
91  AbstractParameter() = default;
92  //AbstractParameter(AbstractParameter&&) = default;
93 
94  // avoid object slicing
95  AbstractParameter(const AbstractParameter&) = delete;
96  AbstractParameter& operator=(const AbstractParameter&) = delete;
97  virtual std::unique_ptr< AbstractParameter > clone() const = 0;
98 };
99 
108 template< Operation >
109 struct OPENPMDAPI_EXPORT Parameter : public AbstractParameter
110 {
111  Parameter() = delete;
112  Parameter(Parameter const &) = delete;
113  Parameter(Parameter &&) = delete;
114 };
115 
116 template<>
117 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_FILE > : public AbstractParameter
118 {
119  Parameter() = default;
120  Parameter(Parameter const & p) :
121  AbstractParameter(), name(p.name), encoding(p.encoding) {}
122 
123  std::unique_ptr< AbstractParameter >
124  clone() const override
125  {
126  return std::unique_ptr< AbstractParameter >(
128  }
129 
130  std::string name = "";
131  IterationEncoding encoding = IterationEncoding::groupBased;
132 };
133 
134 template<>
135 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_FILE > : public AbstractParameter
136 {
137  Parameter() = default;
138  Parameter(Parameter const & p) :
139  AbstractParameter(), name(p.name), encoding(p.encoding) {}
140 
141  std::unique_ptr< AbstractParameter >
142  clone() const override
143  {
144  return std::unique_ptr< AbstractParameter >(
146  }
147 
148  std::string name = "";
149  /*
150  * The backends might need to ensure availability of certain features
151  * for some iteration encodings, e.g. availability of ADIOS steps for
152  * variableBased encoding.
153  */
154  IterationEncoding encoding = IterationEncoding::groupBased;
155 };
156 
157 template<>
158 struct OPENPMDAPI_EXPORT Parameter< Operation::CLOSE_FILE > : public AbstractParameter
159 {
160  Parameter() = default;
161  Parameter( Parameter const & ) : AbstractParameter() {}
162 
163  std::unique_ptr< AbstractParameter >
164  clone() const override
165  {
166  return std::unique_ptr< AbstractParameter >(
167  new Parameter< Operation::CLOSE_FILE >( *this ) );
168  }
169 };
170 
171 template<>
172 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_FILE > : public AbstractParameter
173 {
174  Parameter() = default;
175  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
176 
177  std::unique_ptr< AbstractParameter >
178  clone() const override
179  {
180  return std::unique_ptr< AbstractParameter >(
182  }
183 
184  std::string name = "";
185 };
186 
187 template<>
188 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_PATH > : public AbstractParameter
189 {
190  Parameter() = default;
191  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
192 
193  std::unique_ptr< AbstractParameter >
194  clone() const override
195  {
196  return std::unique_ptr< AbstractParameter >(
198  }
199 
200  std::string path = "";
201 };
202 
203 template<>
204 struct OPENPMDAPI_EXPORT Parameter< Operation::CLOSE_PATH > : public AbstractParameter
205 {
206  Parameter() = default;
207  Parameter( Parameter const & ) : AbstractParameter()
208  {
209  }
210 
211  Parameter &
212  operator=( Parameter const & )
213  {
214  return *this;
215  }
216 
217  std::unique_ptr< AbstractParameter >
218  clone() const override
219  {
220  return std::unique_ptr< AbstractParameter >(
221  new Parameter< Operation::CLOSE_PATH >( *this ) );
222  }
223 };
224 
225 template<>
226 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_PATH > : public AbstractParameter
227 {
228  Parameter() = default;
229  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
230 
231  std::unique_ptr< AbstractParameter >
232  clone() const override
233  {
234  return std::unique_ptr< AbstractParameter >(
236  }
237 
238  std::string path = "";
239 };
240 
241 template<>
242 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_PATH > : public AbstractParameter
243 {
244  Parameter() = default;
245  Parameter(Parameter const & p) : AbstractParameter(), path(p.path) {}
246 
247  std::unique_ptr< AbstractParameter >
248  clone() const override
249  {
250  return std::unique_ptr< AbstractParameter >(
252  }
253 
254  std::string path = "";
255 };
256 
257 template<>
258 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_PATHS > : public AbstractParameter
259 {
260  Parameter() = default;
261  Parameter(Parameter const & p) : AbstractParameter(), paths(p.paths) {}
262 
263  std::unique_ptr< AbstractParameter >
264  clone() const override
265  {
266  return std::unique_ptr< AbstractParameter >(
268  }
269 
270  std::shared_ptr< std::vector< std::string > > paths
271  = std::make_shared< std::vector< std::string > >();
272 };
273 
274 template<>
275 struct OPENPMDAPI_EXPORT Parameter< Operation::CREATE_DATASET > : public AbstractParameter
276 {
277  Parameter() = default;
278  Parameter(Parameter const & p) : AbstractParameter(),
279  name(p.name), extent(p.extent), dtype(p.dtype),
280  chunkSize(p.chunkSize), compression(p.compression),
281  transform(p.transform), options(p.options) {}
282 
283  std::unique_ptr< AbstractParameter >
284  clone() const override
285  {
286  return std::unique_ptr< AbstractParameter >(
288  }
289 
290  std::string name = "";
291  Extent extent = {};
292  Datatype dtype = Datatype::UNDEFINED;
293  Extent chunkSize = {};
294  std::string compression = "";
295  std::string transform = "";
296  std::string options = "{}";
297 };
298 
299 template<>
300 struct OPENPMDAPI_EXPORT Parameter< Operation::EXTEND_DATASET > : public AbstractParameter
301 {
302  Parameter() = default;
303  Parameter(Parameter const & p) : AbstractParameter(), extent(p.extent) {}
304 
305  std::unique_ptr< AbstractParameter >
306  clone() const override
307  {
308  return std::unique_ptr< AbstractParameter >(
310  }
311 
312  Extent extent = {};
313 };
314 
315 template<>
316 struct OPENPMDAPI_EXPORT Parameter< Operation::OPEN_DATASET > : public AbstractParameter
317 {
318  Parameter() = default;
319  Parameter(Parameter const & p) : AbstractParameter(),
320  name(p.name), dtype(p.dtype), extent(p.extent) {}
321 
322  std::unique_ptr< AbstractParameter >
323  clone() const override
324  {
325  return std::unique_ptr< AbstractParameter >(
327  }
328 
329  std::string name = "";
330  std::shared_ptr< Datatype > dtype
331  = std::make_shared< Datatype >();
332  std::shared_ptr< Extent > extent
333  = std::make_shared< Extent >();
334 };
335 
336 template<>
337 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_DATASET > : public AbstractParameter
338 {
339  Parameter() = default;
340  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
341 
342  std::unique_ptr< AbstractParameter >
343  clone() const override
344  {
345  return std::unique_ptr< AbstractParameter >(
347  }
348 
349  std::string name = "";
350 };
351 
352 template<>
353 struct OPENPMDAPI_EXPORT Parameter< Operation::WRITE_DATASET > : public AbstractParameter
354 {
355  Parameter() = default;
357  extent(p.extent), offset(p.offset), dtype(p.dtype),
358  data(p.data) {}
359 
360  Parameter& operator=(const Parameter& p) {
361  this->extent = p.extent;
362  this->offset = p.offset;
363  this->dtype = p.dtype;
364  this->data = p.data;
365  return *this;
366  }
367 
368  std::unique_ptr< AbstractParameter >
369  clone() const override
370  {
371  return std::unique_ptr< AbstractParameter >(
373  }
374 
375  Extent extent = {};
376  Offset offset = {};
377  Datatype dtype = Datatype::UNDEFINED;
378  std::shared_ptr< void const > data = nullptr;
379 };
380 
381 template<>
382 struct OPENPMDAPI_EXPORT Parameter< Operation::READ_DATASET > : public AbstractParameter
383 {
384  Parameter() = default;
386  extent(p.extent), offset(p.offset), dtype(p.dtype),
387  data(p.data) {}
388 
389  Parameter& operator=(const Parameter &p) {
390  this->extent = p.extent;
391  this->offset = p.offset;
392  this->dtype = p.dtype;
393  this->data = p.data;
394  return *this;
395  }
396 
397  std::unique_ptr< AbstractParameter >
398  clone() const override
399  {
400  return std::unique_ptr< AbstractParameter >(
402  }
403 
404  Extent extent = {};
405  Offset offset = {};
406  Datatype dtype = Datatype::UNDEFINED;
407  std::shared_ptr< void > data = nullptr;
408 };
409 
410 template<>
411 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_DATASETS > : public AbstractParameter
412 {
413  Parameter() = default;
414  Parameter(Parameter const & p) : AbstractParameter(),
415  datasets(p.datasets) {}
416 
417  std::unique_ptr< AbstractParameter >
418  clone() const override
419  {
420  return std::unique_ptr< AbstractParameter >(
422  }
423 
424  std::shared_ptr< std::vector< std::string > > datasets
425  = std::make_shared< std::vector< std::string > >();
426 };
427 
428 template<>
429 struct OPENPMDAPI_EXPORT Parameter< Operation::GET_BUFFER_VIEW > : public AbstractParameter
430 {
431  Parameter() = default;
432  Parameter(Parameter const & p) : AbstractParameter(),
433  offset(p.offset), extent(p.extent), dtype(p.dtype), update(p.update),
434  out(p.out)
435  {}
436 
437  std::unique_ptr< AbstractParameter >
438  clone() const override
439  {
440  return std::unique_ptr< AbstractParameter >(
442  }
443 
444  // in parameters
445  Offset offset;
446  Extent extent;
447  Datatype dtype = Datatype::UNDEFINED;
448  bool update = false;
449  // out parameters
450  struct OutParameters
451  {
452  bool backendManagedBuffer = false;
453  unsigned viewIndex = 0;
454  void *ptr = nullptr;
455  };
456  std::shared_ptr< OutParameters > out = std::make_shared< OutParameters >();
457 };
458 
459 template<>
460 struct OPENPMDAPI_EXPORT Parameter< Operation::DELETE_ATT > : public AbstractParameter
461 {
462  Parameter() = default;
463  Parameter(Parameter const & p) : AbstractParameter(), name(p.name) {}
464 
465  std::unique_ptr< AbstractParameter >
466  clone() const override
467  {
468  return std::unique_ptr< AbstractParameter >(
470  }
471 
472  std::string name = "";
473 };
474 
475 template<>
476 struct OPENPMDAPI_EXPORT Parameter< Operation::WRITE_ATT > : public AbstractParameter
477 {
478  Parameter() = default;
479  Parameter(Parameter const & p) : AbstractParameter(),
480  name(p.name), dtype(p.dtype), resource(p.resource) {}
481 
482  std::unique_ptr< AbstractParameter >
483  clone() const override
484  {
485  return std::unique_ptr< AbstractParameter >(
487  }
488 
489  std::string name = "";
490  Datatype dtype = Datatype::UNDEFINED;
491  Attribute::resource resource;
492 };
493 
494 template<>
495 struct OPENPMDAPI_EXPORT Parameter< Operation::READ_ATT > : public AbstractParameter
496 {
497  Parameter() = default;
498  Parameter(Parameter const & p) : AbstractParameter(),
499  name(p.name), dtype(p.dtype), resource(p.resource) {}
500 
501  Parameter& operator=(const Parameter &p) {
502  this->name = p.name;
503  this->dtype = p.dtype;
504  this->resource = p.resource;
505  return *this;
506  }
507 
508  std::unique_ptr< AbstractParameter >
509  clone() const override
510  {
511  return std::unique_ptr< AbstractParameter >(
513  }
514 
515  std::string name = "";
516  std::shared_ptr< Datatype > dtype
517  = std::make_shared< Datatype >();
518  std::shared_ptr< Attribute::resource > resource
519  = std::make_shared< Attribute::resource >();
520 };
521 
522 template<>
523 struct OPENPMDAPI_EXPORT Parameter< Operation::LIST_ATTS > : public AbstractParameter
524 {
525  Parameter() = default;
526  Parameter(Parameter const & p) : AbstractParameter(),
527  attributes(p.attributes) {}
528 
529  std::unique_ptr< AbstractParameter >
530  clone() const override
531  {
532  return std::unique_ptr< AbstractParameter >(
534  }
535 
536  std::shared_ptr< std::vector< std::string > > attributes
537  = std::make_shared< std::vector< std::string > >();
538 };
539 
540 template<>
541 struct OPENPMDAPI_EXPORT Parameter< Operation::ADVANCE > : public AbstractParameter
542 {
543  Parameter() = default;
544  Parameter( Parameter const & p )
545  : AbstractParameter(), mode( p.mode ), status( p.status )
546  {
547  }
548 
549  std::unique_ptr< AbstractParameter >
550  clone() const override
551  {
552  return std::unique_ptr< AbstractParameter >(
553  new Parameter< Operation::ADVANCE >( *this ) );
554  }
555 
559  std::shared_ptr< AdvanceStatus > status =
560  std::make_shared< AdvanceStatus >( AdvanceStatus::OK );
561 };
562 
563 template<>
564 struct OPENPMDAPI_EXPORT Parameter< Operation::AVAILABLE_CHUNKS >
565  : public AbstractParameter
566 {
567  Parameter() = default;
568  Parameter( Parameter const & p ) : AbstractParameter(), chunks( p.chunks )
569  {
570  }
571 
572  Parameter &
573  operator=( Parameter const & p )
574  {
575  chunks = p.chunks;
576  return *this;
577  }
578 
579  std::unique_ptr< AbstractParameter >
580  clone() const override
581  {
582  return std::unique_ptr< AbstractParameter >(
584  }
585 
586  // output parameter
587  std::shared_ptr< ChunkTable > chunks = std::make_shared< ChunkTable >();
588 };
589 
598 class OPENPMDAPI_EXPORT IOTask
599 {
600 public:
607  template< Operation op >
608  explicit IOTask(Writable* w,
609  Parameter< op > const & p)
610  : writable{w},
611  operation{op},
612  parameter{p.clone()}
613  { }
614 
615  template< Operation op >
616  explicit IOTask(AttributableInterface* a,
617  Parameter< op > const & p)
618  : writable{getWritable(a)},
619  operation{op},
620  parameter{p.clone()}
621  { }
622 
623  explicit IOTask(IOTask const & other) :
624  writable{other.writable},
625  operation{other.operation},
626  parameter{other.parameter}
627  {}
628 
629  IOTask& operator=(IOTask const & other)
630  {
631  writable = other.writable;
632  operation = other.operation;
633  parameter = other.parameter;
634  return *this;
635  }
636 
637  Writable* writable;
638  Operation operation;
639  std::shared_ptr< AbstractParameter > parameter;
640 }; // IOTask
641 } // namespace openPMD
Self-contained description of a single IO operation.
Definition: IOTask.hpp:598
AdvanceMode mode
input parameter
Definition: IOTask.hpp:557
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:29
Layer to mirror structure of logical data and persistent data in file.
Definition: Writable.hpp:64
Typesafe description of all required arguments for a specified Operation.
Definition: IOTask.hpp:109
OPENPMDAPI_EXPORT_ENUM_CLASS(Operation)
Type of IO operation between logical and persistent data.
Definition: IOTask.hpp:48
Layer to manage storage of attributes associated with file objects.
Definition: Attributable.hpp:115
Definition: IOTask.hpp:88
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:608