PMDK C++ bindings  1.8.1
This is the C++ bindings documentation for PMDK's libpmemobj.
pool.hpp
Go to the documentation of this file.
1 /*
2  * Copyright 2016-2019, Intel Corporation
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  *
16  * * Neither the name of the copyright holder nor the names of its
17  * contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
38 #ifndef LIBPMEMOBJ_CPP_POOL_HPP
39 #define LIBPMEMOBJ_CPP_POOL_HPP
40 
41 #include <cstddef>
42 #include <string>
43 #include <sys/stat.h>
44 
47 #include <libpmemobj++/p.hpp>
49 #include <libpmemobj/pool_base.h>
50 
51 namespace pmem
52 {
53 
54 namespace obj
55 {
56 template <typename T>
57 class persistent_ptr;
58 
67 class pool_base {
68 public:
72  pool_base() noexcept : pop(nullptr)
73  {
74  }
75 
83  explicit pool_base(pmemobjpool *cpop) noexcept : pop(cpop)
84  {
85  }
86 
90  pool_base(const pool_base &) noexcept = default;
91 
95  pool_base(pool_base &&) noexcept = default;
96 
100  pool_base &operator=(const pool_base &) noexcept = default;
101 
105  pool_base &operator=(pool_base &&) noexcept = default;
106 
110  virtual ~pool_base() noexcept = default;
111 
124  static pool_base
125  open(const std::string &path, const std::string &layout)
126  {
127 #ifdef _WIN32
128  pmemobjpool *pop = pmemobj_openU(path.c_str(), layout.c_str());
129 #else
130  pmemobjpool *pop = pmemobj_open(path.c_str(), layout.c_str());
131 #endif
132  if (pop == nullptr)
133  throw pmem::pool_error("Failed opening pool")
134  .with_pmemobj_errormsg();
135 
136  return pool_base(pop);
137  }
138 
155  static pool_base
156  create(const std::string &path, const std::string &layout,
157  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
158  {
159 #ifdef _WIN32
160  pmemobjpool *pop = pmemobj_createU(path.c_str(), layout.c_str(),
161  size, mode);
162 #else
163  pmemobjpool *pop = pmemobj_create(path.c_str(), layout.c_str(),
164  size, mode);
165 #endif
166  if (pop == nullptr)
167  throw pmem::pool_error("Failed creating pool")
168  .with_pmemobj_errormsg();
169 
170  return pool_base(pop);
171  }
172 
183  static int
184  check(const std::string &path, const std::string &layout) noexcept
185  {
186 #ifdef _WIN32
187  return pmemobj_checkU(path.c_str(), layout.c_str());
188 #else
189  return pmemobj_check(path.c_str(), layout.c_str());
190 #endif
191  }
192 
193 #ifdef _WIN32
194 
207  static pool_base
208  open(const std::wstring &path, const std::wstring &layout)
209  {
210  pmemobjpool *pop = pmemobj_openW(path.c_str(), layout.c_str());
211  if (pop == nullptr)
212  throw pmem::pool_error("Failed opening pool")
213  .with_pmemobj_errormsg();
214 
215  return pool_base(pop);
216  }
217 
235  static pool_base
236  create(const std::wstring &path, const std::wstring &layout,
237  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
238  {
239  pmemobjpool *pop = pmemobj_createW(path.c_str(), layout.c_str(),
240  size, mode);
241  if (pop == nullptr)
242  throw pmem::pool_error("Failed creating pool")
243  .with_pmemobj_errormsg();
244 
245  return pool_base(pop);
246  }
247 
259  static int
260  check(const std::wstring &path, const std::wstring &layout) noexcept
261  {
262  return pmemobj_checkW(path.c_str(), layout.c_str());
263  }
264 #endif
265 
271  void
273  {
274  if (this->pop == nullptr)
275  throw std::logic_error("Pool already closed");
276 
277  pmemobj_close(this->pop);
278  this->pop = nullptr;
279  }
280 
287  void
288  persist(const void *addr, size_t len) noexcept
289  {
290  pmemobj_persist(this->pop, addr, len);
291  }
292 
298  template <typename Y>
299  void
300  persist(const p<Y> &prop) noexcept
301  {
302  pmemobj_persist(this->pop, &prop, sizeof(Y));
303  }
304 
311  template <typename Y>
312  void
313  persist(const persistent_ptr<Y> &ptr) noexcept
314  {
315  pmemobj_persist(this->pop, &ptr, sizeof(ptr));
316  }
317 
324  void
325  flush(const void *addr, size_t len) noexcept
326  {
327  pmemobj_flush(this->pop, addr, len);
328  }
329 
335  template <typename Y>
336  void
337  flush(const p<Y> &prop) noexcept
338  {
339  pmemobj_flush(this->pop, &prop, sizeof(Y));
340  }
341 
347  template <typename Y>
348  void
349  flush(const persistent_ptr<Y> &ptr) noexcept
350  {
351  pmemobj_flush(this->pop, &ptr, sizeof(ptr));
352  }
353 
357  void
358  drain(void) noexcept
359  {
360  pmemobj_drain(this->pop);
361  }
362 
373  void *
374  memcpy_persist(void *dest, const void *src, size_t len) noexcept
375  {
376  return pmemobj_memcpy_persist(this->pop, dest, src, len);
377  }
378 
389  void *
390  memset_persist(void *dest, int c, size_t len) noexcept
391  {
392  return pmemobj_memset_persist(this->pop, dest, c, len);
393  }
394 
402  PMEMobjpool *
403  handle() noexcept
404  {
405  return this->pop;
406  }
407 
408  POBJ_CPP_DEPRECATED PMEMobjpool *
409  get_handle() noexcept
410  {
411  return pool_base::handle();
412  }
413 
414 protected:
415  /* The pool opaque handle */
416  PMEMobjpool *pop;
417 
418 #ifndef _WIN32
419  /* Default create mode */
420  static const int DEFAULT_MODE = S_IWUSR | S_IRUSR;
421 #else
422  /* Default create mode */
423  static const int DEFAULT_MODE = S_IWRITE | S_IREAD;
424 #endif
425 };
426 
435 template <typename T>
436 class pool : public pool_base {
437 public:
441  pool() noexcept = default;
442 
446  pool(const pool &) noexcept = default;
447 
451  pool(pool &&) noexcept = default;
452 
456  pool &operator=(const pool &) noexcept = default;
457 
461  pool &operator=(pool &&) noexcept = default;
462 
466  ~pool() noexcept = default;
467 
471  explicit pool(const pool_base &pb) noexcept : pool_base(pb)
472  {
473  }
474 
478  explicit pool(pool_base &&pb) noexcept : pool_base(pb)
479  {
480  }
481 
492  template <typename M>
493  M
494  ctl_get(const std::string &name)
495  {
496  return ctl_get_detail<M>(pop, name);
497  }
498 
510  template <typename M>
511  M
512  ctl_set(const std::string &name, M arg)
513  {
514  return ctl_set_detail(pop, name, arg);
515  }
516 
528  template <typename M>
529  M
530  ctl_exec(const std::string &name, M arg)
531  {
532  return ctl_exec_detail(pop, name, arg);
533  }
534 
535 #ifdef _WIN32
536 
546  template <typename M>
547  M
548  ctl_get(const std::wstring &name)
549  {
550  return ctl_get_detail<M>(pop, name);
551  }
552 
564  template <typename M>
565  M
566  ctl_set(const std::wstring &name, M arg)
567  {
568  return ctl_set_detail(pop, name, arg);
569  }
570 
582  template <typename M>
583  M
584  ctl_exec(const std::wstring &name, M arg)
585  {
586  return ctl_exec_detail(pop, name, arg);
587  }
588 #endif
589 
597  {
598  if (pop == nullptr)
599  throw pmem::pool_error("Invalid pool handle");
600 
601  persistent_ptr<T> root = pmemobj_root(this->pop, sizeof(T));
602  return root;
603  }
604 
605  POBJ_CPP_DEPRECATED persistent_ptr<T>
606  get_root()
607  {
608  return pool::root();
609  }
610 
623  static pool<T>
624  open(const std::string &path, const std::string &layout)
625  {
626  return pool<T>(pool_base::open(path, layout));
627  }
628 
645  static pool<T>
646  create(const std::string &path, const std::string &layout,
647  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
648  {
649  return pool<T>(pool_base::create(path, layout, size, mode));
650  }
651 
662  static int
663  check(const std::string &path, const std::string &layout)
664  {
665  return pool_base::check(path, layout);
666  }
667 
668 #ifdef _WIN32
669 
682  static pool<T>
683  open(const std::wstring &path, const std::wstring &layout)
684  {
685  return pool<T>(pool_base::open(path, layout));
686  }
687 
705  static pool<T>
706  create(const std::wstring &path, const std::wstring &layout,
707  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
708  {
709  return pool<T>(pool_base::create(path, layout, size, mode));
710  }
711 
723  static int
724  check(const std::wstring &path, const std::wstring &layout)
725  {
726  return pool_base::check(path, layout);
727  }
728 #endif
729 };
730 
741 template <typename T>
742 T
743 ctl_get(const std::string &name)
744 {
745  return ctl_get_detail<T>(nullptr, name);
746 }
747 
759 template <typename T>
760 T
761 ctl_set(const std::string &name, T arg)
762 {
763  return ctl_set_detail(nullptr, name, arg);
764 }
765 
777 template <typename T>
778 T
779 ctl_exec(const std::string &name, T arg)
780 {
781  return ctl_exec_detail(nullptr, name, arg);
782 }
783 
784 #ifdef _WIN32
785 
795 template <typename T>
796 T
797 ctl_get(const std::wstring &name)
798 {
799  return ctl_get_detail<T>(nullptr, name);
800 }
801 
813 template <typename T>
814 T
815 ctl_set(const std::wstring &name, T arg)
816 {
817  return ctl_set_detail(nullptr, name, arg);
818 }
819 
831 template <typename T>
832 T
833 ctl_exec(const std::wstring &name, T arg)
834 {
835  return ctl_exec_detail(nullptr, name, arg);
836 }
837 #endif
838 
839 } /* namespace obj */
840 
841 } /* namespace pmem */
842 
843 #endif /* LIBPMEMOBJ_CPP_POOL_HPP */
pmem::obj::ctl_get
T ctl_get(const std::string &name)
Query libpmemobj state at global scope.
Definition: pool.hpp:743
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:374
pmem::obj::pool_base::persist
void persist(const persistent_ptr< Y > &ptr) noexcept
Performs persist operation on a given persistent pointer.
Definition: pool.hpp:313
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:236
pmem::obj::pool::ctl_exec
M ctl_exec(const std::string &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:530
pmem::pool_error
Custom pool error class.
Definition: pexceptions.hpp:72
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:724
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:646
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:288
pmem
A persistent version of concurrent hash map implementation Ref: https://arxiv.org/abs/1509....
Definition: allocation_flag.hpp:44
pmem::obj::pool::ctl_get
M ctl_get(const std::string &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:494
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:390
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:478
pmem::obj::pool::ctl_get
M ctl_get(const std::wstring &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:548
pmem::obj::pool::ctl_set
M ctl_set(const std::wstring &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:566
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:184
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:260
pmem::obj::pool_base::drain
void drain(void) noexcept
Performs drain operation.
Definition: pool.hpp:358
pmem::obj::pool_base::persist
void persist(const p< Y > &prop) noexcept
Performs persist operation on a given pmem property.
Definition: pool.hpp:300
pmem::obj::p
Resides on pmem class.
Definition: p.hpp:64
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:125
pmem::obj::pool_base::close
void close()
Closes the pool.
Definition: pool.hpp:272
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:596
pmem::obj::pool_base::pool_base
pool_base() noexcept
Defaulted constructor.
Definition: pool.hpp:72
pmem::obj::pool_base::flush
void flush(const persistent_ptr< Y > &ptr) noexcept
Performs flush operation on a given persistent object.
Definition: pool.hpp:349
pmem::obj::pool::pool
pool() noexcept=default
Defaulted constructor.
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:325
pmem::obj::pool_base::handle
PMEMobjpool * handle() noexcept
Gets the C style handle to the pool.
Definition: pool.hpp:403
pmem::obj::ctl_set
T ctl_set(const std::string &name, T arg)
Modify libpmemobj state at global scope.
Definition: pool.hpp:761
pmem::obj::pool_base::pool_base
pool_base(pmemobjpool *cpop) noexcept
Explicit constructor.
Definition: pool.hpp:83
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:156
pmem::obj::pool::ctl_set
M ctl_set(const std::string &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:512
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:132
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:208
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:436
p.hpp
Resides on pmem property template.
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:624
pmem::obj::ctl_exec
T ctl_exec(const std::string &name, T arg)
Execute function at global scope.
Definition: pool.hpp:779
pmem::obj::pool::ctl_exec
M ctl_exec(const std::wstring &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:584
std
A persistent version of concurrent hash map implementation Ref: https://arxiv.org/abs/1509....
Definition: concurrent_hash_map.hpp:66
pmem::obj::pool_base::flush
void flush(const p< Y > &prop) noexcept
Performs flush operation on a given pmem property.
Definition: pool.hpp:337
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:683
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:706
pmem::obj::pool_base
The non-template pool base class.
Definition: pool.hpp:67
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:663