PMDK C++ bindings  1.12.1-rc1
This is the C++ bindings documentation for PMDK's libpmemobj.
pool.hpp
Go to the documentation of this file.
1 // SPDX-License-Identifier: BSD-3-Clause
2 /* Copyright 2016-2021, Intel Corporation */
3 
9 #ifndef LIBPMEMOBJ_CPP_POOL_HPP
10 #define LIBPMEMOBJ_CPP_POOL_HPP
11 
12 #include <cstddef>
13 #include <functional>
14 #include <mutex>
15 #include <string>
16 #include <sys/stat.h>
17 #include <typeindex>
18 #include <unordered_map>
19 #include <vector>
20 
24 #include <libpmemobj++/p.hpp>
27 #include <libpmemobj/atomic_base.h>
28 #include <libpmemobj/pool_base.h>
29 
30 namespace pmem
31 {
32 
33 namespace obj
34 {
35 template <typename T>
36 class persistent_ptr;
37 
46 class pool_base {
47 public:
51  pool_base() noexcept : pop(nullptr)
52  {
53  }
54 
62  explicit pool_base(pmemobjpool *cpop) noexcept : pop(cpop)
63  {
64  }
65 
69  pool_base(const pool_base &) noexcept = default;
70 
74  pool_base(pool_base &&) noexcept = default;
75 
79  pool_base &operator=(const pool_base &) noexcept = default;
80 
84  pool_base &operator=(pool_base &&) noexcept = default;
85 
89  virtual ~pool_base() noexcept = default;
90 
103  static pool_base
104  open(const std::string &path, const std::string &layout)
105  {
106 #ifdef _WIN32
107  pmemobjpool *pop = pmemobj_openU(path.c_str(), layout.c_str());
108 #else
109  pmemobjpool *pop = pmemobj_open(path.c_str(), layout.c_str());
110 #endif
111  if (pop == nullptr)
112  throw pmem::pool_error("Failed opening pool")
113  .with_pmemobj_errormsg();
114 
115  pmemobj_set_user_data(pop, new detail::pool_data);
116 
117  return pool_base(pop);
118  }
119 
136  static pool_base
137  create(const std::string &path, const std::string &layout,
138  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
139  {
140 #ifdef _WIN32
141  pmemobjpool *pop = pmemobj_createU(path.c_str(), layout.c_str(),
142  size, mode);
143 #else
144  pmemobjpool *pop = pmemobj_create(path.c_str(), layout.c_str(),
145  size, mode);
146 #endif
147  if (pop == nullptr)
148  throw pmem::pool_error("Failed creating pool")
149  .with_pmemobj_errormsg();
150 
151  pmemobj_set_user_data(pop, new detail::pool_data);
152 
153  return pool_base(pop);
154  }
155 
166  static int
167  check(const std::string &path, const std::string &layout) noexcept
168  {
169 #ifdef _WIN32
170  return pmemobj_checkU(path.c_str(), layout.c_str());
171 #else
172  return pmemobj_check(path.c_str(), layout.c_str());
173 #endif
174  }
175 
176 #ifdef _WIN32
177 
190  static pool_base
191  open(const std::wstring &path, const std::wstring &layout)
192  {
193  pmemobjpool *pop = pmemobj_openW(path.c_str(), layout.c_str());
194  if (pop == nullptr)
195  throw pmem::pool_error("Failed opening pool")
196  .with_pmemobj_errormsg();
197 
198  pmemobj_set_user_data(pop, new detail::pool_data);
199 
200  return pool_base(pop);
201  }
202 
220  static pool_base
221  create(const std::wstring &path, const std::wstring &layout,
222  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
223  {
224  pmemobjpool *pop = pmemobj_createW(path.c_str(), layout.c_str(),
225  size, mode);
226  if (pop == nullptr)
227  throw pmem::pool_error("Failed creating pool")
228  .with_pmemobj_errormsg();
229 
230  pmemobj_set_user_data(pop, new detail::pool_data);
231 
232  return pool_base(pop);
233  }
234 
246  static int
247  check(const std::wstring &path, const std::wstring &layout) noexcept
248  {
249  return pmemobj_checkW(path.c_str(), layout.c_str());
250  }
251 #endif
252 
258  void
260  {
261  if (this->pop == nullptr)
262  throw std::logic_error("Pool already closed");
263 
264  auto *user_data = static_cast<detail::pool_data *>(
265  pmemobj_get_user_data(this->pop));
266 
267  if (user_data->initialized.load())
268  user_data->cleanup();
269 
270  delete user_data;
271 
272  pmemobj_close(this->pop);
273  this->pop = nullptr;
274  }
275 
282  void
283  persist(const void *addr, size_t len) noexcept
284  {
285  pmemobj_persist(this->pop, addr, len);
286  }
287 
293  template <typename Y>
294  void
295  persist(const p<Y> &prop) noexcept
296  {
297  pmemobj_persist(this->pop, &prop, sizeof(Y));
298  }
299 
306  template <typename Y>
307  void
308  persist(const persistent_ptr<Y> &ptr) noexcept
309  {
310  pmemobj_persist(this->pop, &ptr, sizeof(ptr));
311  }
312 
319  void
320  flush(const void *addr, size_t len) noexcept
321  {
322  pmemobj_flush(this->pop, addr, len);
323  }
324 
330  template <typename Y>
331  void
332  flush(const p<Y> &prop) noexcept
333  {
334  pmemobj_flush(this->pop, &prop, sizeof(Y));
335  }
336 
342  template <typename Y>
343  void
344  flush(const persistent_ptr<Y> &ptr) noexcept
345  {
346  pmemobj_flush(this->pop, &ptr, sizeof(ptr));
347  }
348 
352  void
353  drain(void) noexcept
354  {
355  pmemobj_drain(this->pop);
356  }
357 
368  void *
369  memcpy_persist(void *dest, const void *src, size_t len) noexcept
370  {
371  return pmemobj_memcpy_persist(this->pop, dest, src, len);
372  }
373 
384  void *
385  memset_persist(void *dest, int c, size_t len) noexcept
386  {
387  return pmemobj_memset_persist(this->pop, dest, c, len);
388  }
389 
397  PMEMobjpool *
398  handle() noexcept
399  {
400  return this->pop;
401  }
402 
403  POBJ_CPP_DEPRECATED PMEMobjpool *
404  get_handle() noexcept
405  {
406  return pool_base::handle();
407  }
408 
422  pobj_defrag_result
423  defrag(persistent_ptr_base **ptrv, size_t oidcnt)
424  {
425  pobj_defrag_result result;
426  int ret = pmemobj_defrag(this->pop, (PMEMoid **)ptrv, oidcnt,
427  &result);
428 
429  if (ret != 0)
430  throw defrag_error(result, "Defragmentation failed")
431  .with_pmemobj_errormsg();
432 
433  return result;
434  }
435 
436 protected:
437  /* The pool opaque handle */
438  PMEMobjpool *pop;
439 
440 #ifndef _WIN32
441  /* Default create mode */
442  static const int DEFAULT_MODE = S_IWUSR | S_IRUSR;
443 #else
444  /* Default create mode */
445  static const int DEFAULT_MODE = S_IWRITE | S_IREAD;
446 #endif
447 };
448 
464 template <typename T>
465 class pool : public pool_base {
466 public:
470  pool() noexcept = default;
471 
475  pool(const pool &) noexcept = default;
476 
480  pool(pool &&) noexcept = default;
481 
485  pool &operator=(const pool &) noexcept = default;
486 
490  pool &operator=(pool &&) noexcept = default;
491 
495  ~pool() noexcept = default;
496 
500  explicit pool(const pool_base &pb) noexcept : pool_base(pb)
501  {
502  }
503 
507  explicit pool(pool_base &&pb) noexcept : pool_base(pb)
508  {
509  }
510 
521  template <typename M>
522  M
523  ctl_get(const std::string &name)
524  {
525  return ctl_get_detail<M>(pop, name);
526  }
527 
539  template <typename M>
540  M
541  ctl_set(const std::string &name, M arg)
542  {
543  return ctl_set_detail(pop, name, arg);
544  }
545 
557  template <typename M>
558  M
559  ctl_exec(const std::string &name, M arg)
560  {
561  return ctl_exec_detail(pop, name, arg);
562  }
563 
564 #ifdef _WIN32
565 
575  template <typename M>
576  M
577  ctl_get(const std::wstring &name)
578  {
579  return ctl_get_detail<M>(pop, name);
580  }
581 
593  template <typename M>
594  M
595  ctl_set(const std::wstring &name, M arg)
596  {
597  return ctl_set_detail(pop, name, arg);
598  }
599 
611  template <typename M>
612  M
613  ctl_exec(const std::wstring &name, M arg)
614  {
615  return ctl_exec_detail(pop, name, arg);
616  }
617 #endif
618 
628  {
629  if (pop == nullptr)
630  throw pmem::pool_error("Invalid pool handle");
631 
632  persistent_ptr<T> root = pmemobj_root(this->pop, sizeof(T));
633  return root;
634  }
635 
636  POBJ_CPP_DEPRECATED persistent_ptr<T>
637  get_root()
638  {
639  return pool::root();
640  }
641 
654  static pool<T>
655  open(const std::string &path, const std::string &layout)
656  {
657  return pool<T>(pool_base::open(path, layout));
658  }
659 
676  static pool<T>
677  create(const std::string &path, const std::string &layout,
678  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
679  {
680  return pool<T>(pool_base::create(path, layout, size, mode));
681  }
682 
693  static int
694  check(const std::string &path, const std::string &layout)
695  {
696  return pool_base::check(path, layout);
697  }
698 
699 #ifdef _WIN32
700 
713  static pool<T>
714  open(const std::wstring &path, const std::wstring &layout)
715  {
716  return pool<T>(pool_base::open(path, layout));
717  }
718 
736  static pool<T>
737  create(const std::wstring &path, const std::wstring &layout,
738  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
739  {
740  return pool<T>(pool_base::create(path, layout, size, mode));
741  }
742 
754  static int
755  check(const std::wstring &path, const std::wstring &layout)
756  {
757  return pool_base::check(path, layout);
758  }
759 #endif
760 };
761 
772 template <typename T>
773 T
774 ctl_get(const std::string &name)
775 {
776  return ctl_get_detail<T>(nullptr, name);
777 }
778 
790 template <typename T>
791 T
792 ctl_set(const std::string &name, T arg)
793 {
794  return ctl_set_detail(nullptr, name, arg);
795 }
796 
808 template <typename T>
809 T
810 ctl_exec(const std::string &name, T arg)
811 {
812  return ctl_exec_detail(nullptr, name, arg);
813 }
814 
815 #ifdef _WIN32
816 
826 template <typename T>
827 T
828 ctl_get(const std::wstring &name)
829 {
830  return ctl_get_detail<T>(nullptr, name);
831 }
832 
844 template <typename T>
845 T
846 ctl_set(const std::wstring &name, T arg)
847 {
848  return ctl_set_detail(nullptr, name, arg);
849 }
850 
862 template <typename T>
863 T
864 ctl_exec(const std::wstring &name, T arg)
865 {
866  return ctl_exec_detail(nullptr, name, arg);
867 }
868 #endif
869 
870 } /* namespace obj */
871 
872 } /* namespace pmem */
873 
874 #endif /* LIBPMEMOBJ_CPP_POOL_HPP */
pmem::obj::pool_base::memcpy_persist
void * memcpy_persist(void *dest, const void *src, size_t len) noexcept
Performs memcpy and persist operation on a given chunk of memory.
Definition: pool.hpp:369
pmem::obj::ctl_exec
T ctl_exec(const std::string &name, T arg)
Execute function at global scope.
Definition: pool.hpp:810
pmem::obj::pool_base::persist
void persist(const persistent_ptr< Y > &ptr) noexcept
Performs persist operation on a given persistent pointer.
Definition: pool.hpp:308
pmem::obj::pool_base::create
static pool_base create(const std::wstring &path, const std::wstring &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
Creates a new transactional object store pool.
Definition: pool.hpp:221
pmem::obj::pool::ctl_exec
M ctl_exec(const std::string &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:559
pmem::pool_error
Custom pool error class.
Definition: pexceptions.hpp:47
pmem::obj::pool_base::pool_base
pool_base(const pool_base &) noexcept=default
Defaulted copy constructor.
pmem::obj::pool::check
static int check(const std::wstring &path, const std::wstring &layout)
Checks if a given pool is consistent.
Definition: pool.hpp:755
pmem::obj::pool::create
static pool< T > create(const std::string &path, const std::string &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
Creates a new transactional object store pool.
Definition: pool.hpp:677
pmem::obj::pool_base::persist
void persist(const void *addr, size_t len) noexcept
Performs persist operation on a given chunk of memory.
Definition: pool.hpp:283
pmem
Persistent memory namespace.
Definition: allocation_flag.hpp:15
pmem::obj::pool::ctl_get
M ctl_get(const std::string &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:523
pmem::obj::pool_base::memset_persist
void * memset_persist(void *dest, int c, size_t len) noexcept
Performs memset and persist operation on a given chunk of memory.
Definition: pool.hpp:385
ctl.hpp
C++ ctl api.
common.hpp
Commonly used functionality.
pmem::obj::pool::pool
pool(pool_base &&pb) noexcept
Defaulted move constructor.
Definition: pool.hpp:507
pmem::obj::pool::ctl_get
M ctl_get(const std::wstring &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:577
pmem::obj::pool::ctl_set
M ctl_set(const std::wstring &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:595
pmem::obj::pool_base::check
static int check(const std::string &path, const std::string &layout) noexcept
Checks if a given pool is consistent.
Definition: pool.hpp:167
pmem::obj::pool_base::defrag
pobj_defrag_result defrag(persistent_ptr_base **ptrv, size_t oidcnt)
Starts defragmentation using selected pointers within this pool.
Definition: pool.hpp:423
pmem::obj::pool_base::pool_base
pool_base(pool_base &&) noexcept=default
Defaulted move constructor.
pexceptions.hpp
Custom exceptions.
pmem::obj::pool_base::check
static int check(const std::wstring &path, const std::wstring &layout) noexcept
Checks if a given pool is consistent.
Definition: pool.hpp:247
pmem::obj::pool_base::drain
void drain(void) noexcept
Performs drain operation.
Definition: pool.hpp:353
pmem::obj::pool_base::persist
void persist(const p< Y > &prop) noexcept
Performs persist operation on a given pmem property.
Definition: pool.hpp:295
pmem::obj::p
Resides on pmem class.
Definition: p.hpp:35
pmem::obj::pool_base::open
static pool_base open(const std::string &path, const std::string &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:104
pmem::obj::pool_base::close
void close()
Closes the pool.
Definition: pool.hpp:259
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:627
pmem::obj::pool_base::pool_base
pool_base() noexcept
Defaulted constructor.
Definition: pool.hpp:51
pmem::obj::pool_base::flush
void flush(const persistent_ptr< Y > &ptr) noexcept
Performs flush operation on a given persistent object.
Definition: pool.hpp:344
pmem::obj::pool::pool
pool() noexcept=default
Defaulted constructor.
pmem::obj::ctl_set
T ctl_set(const std::string &name, T arg)
Modify libpmemobj state at global scope.
Definition: pool.hpp:792
pmem::obj::pool_base::flush
void flush(const void *addr, size_t len) noexcept
Performs flush operation on a given chunk of memory.
Definition: pool.hpp:320
pmem::obj::pool_base::handle
PMEMobjpool * handle() noexcept
Gets the C style handle to the pool.
Definition: pool.hpp:398
pmem::obj::pool_base::pool_base
pool_base(pmemobjpool *cpop) noexcept
Explicit constructor.
Definition: pool.hpp:62
pmem::obj::pool_base::create
static pool_base create(const std::string &path, const std::string &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
Creates a new transactional object store pool.
Definition: pool.hpp:137
pmem::obj::pool::ctl_set
M ctl_set(const std::string &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:541
pmem::defrag_error
Custom defrag error class.
Definition: pexceptions.hpp:212
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:152
pmem::obj::pool_base::open
static pool_base open(const std::wstring &path, const std::wstring &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:191
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:465
p.hpp
Resides on pmem property template.
pmem::obj::ctl_get
T ctl_get(const std::string &name)
Query libpmemobj state at global scope.
Definition: pool.hpp:774
pmem::obj::pool::open
static pool< T > open(const std::string &path, const std::string &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:655
pmem::obj::pool::ctl_exec
M ctl_exec(const std::wstring &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:613
pmem::obj::pool_base::flush
void flush(const p< Y > &prop) noexcept
Performs flush operation on a given pmem property.
Definition: pool.hpp:332
pool_data.hpp
A volatile data stored along with pmemobjpool.
pmem::obj::persistent_ptr_base
Persistent_ptr base (non-template) class.
Definition: persistent_ptr_base.hpp:42
persistent_ptr_base.hpp
Base class for persistent_ptr.
pmem::obj::pool::open
static pool< T > open(const std::wstring &path, const std::wstring &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:714
pmem::obj::pool::create
static pool< T > create(const std::wstring &path, const std::wstring &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
Creates a new transactional object store pool.
Definition: pool.hpp:737
pmem::obj::pool_base
The non-template pool base class.
Definition: pool.hpp:46
pmem::obj::pool::check
static int check(const std::string &path, const std::string &layout)
Checks if a given pool is consistent.
Definition: pool.hpp:694