PMDK C++ bindings  1.7
This is the C++ bindings documentation for PMDK's libpmemobj.
pool.hpp
Go to the documentation of this file.
1 /*
2  * Copyright 2016-2018, 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 
48 #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 pool_error("Failed opening pool");
134 
135  return pool_base(pop);
136  }
137 
154  static pool_base
155  create(const std::string &path, const std::string &layout,
156  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
157  {
158 #ifdef _WIN32
159  pmemobjpool *pop = pmemobj_createU(path.c_str(), layout.c_str(),
160  size, mode);
161 #else
162  pmemobjpool *pop = pmemobj_create(path.c_str(), layout.c_str(),
163  size, mode);
164 #endif
165  if (pop == nullptr)
166  throw pool_error("Failed creating pool");
167 
168  return pool_base(pop);
169  }
170 
181  static int
182  check(const std::string &path, const std::string &layout) noexcept
183  {
184 #ifdef _WIN32
185  return pmemobj_checkU(path.c_str(), layout.c_str());
186 #else
187  return pmemobj_check(path.c_str(), layout.c_str());
188 #endif
189  }
190 
191 #ifdef _WIN32
192 
205  static pool_base
206  open(const std::wstring &path, const std::wstring &layout)
207  {
208  pmemobjpool *pop = pmemobj_openW(path.c_str(), layout.c_str());
209  if (pop == nullptr)
210  throw pool_error("Failed opening pool");
211 
212  return pool_base(pop);
213  }
214 
232  static pool_base
233  create(const std::wstring &path, const std::wstring &layout,
234  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
235  {
236  pmemobjpool *pop = pmemobj_createW(path.c_str(), layout.c_str(),
237  size, mode);
238  if (pop == nullptr)
239  throw pool_error("Failed creating pool");
240 
241  return pool_base(pop);
242  }
243 
255  static int
256  check(const std::wstring &path, const std::wstring &layout) noexcept
257  {
258  return pmemobj_checkW(path.c_str(), layout.c_str());
259  }
260 #endif
261 
267  void
269  {
270  if (this->pop == nullptr)
271  throw std::logic_error("Pool already closed");
272 
273  pmemobj_close(this->pop);
274  this->pop = nullptr;
275  }
276 
283  void
284  persist(const void *addr, size_t len) noexcept
285  {
286  pmemobj_persist(this->pop, addr, len);
287  }
288 
294  template <typename Y>
295  void
296  persist(const p<Y> &prop) noexcept
297  {
298  pmemobj_persist(this->pop, &prop, sizeof(Y));
299  }
300 
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 
409 protected:
410  /* The pool opaque handle */
411  PMEMobjpool *pop;
412 
413 #ifndef _WIN32
414  /* Default create mode */
415  static const int DEFAULT_MODE = S_IWUSR | S_IRUSR;
416 #else
417  /* Default create mode */
418  static const int DEFAULT_MODE = S_IWRITE | S_IREAD;
419 #endif
420 };
421 
430 template <typename T>
431 class pool : public pool_base {
432 public:
436  pool() noexcept = default;
437 
441  pool(const pool &) noexcept = default;
442 
446  pool(pool &&) noexcept = default;
447 
451  pool &operator=(const pool &) noexcept = default;
452 
456  pool &operator=(pool &&) noexcept = default;
457 
461  ~pool() noexcept = default;
462 
466  explicit pool(const pool_base &pb) noexcept : pool_base(pb)
467  {
468  }
469 
473  explicit pool(pool_base &&pb) noexcept : pool_base(pb)
474  {
475  }
476 
487  template <typename M>
488  M
489  ctl_get(const std::string &name)
490  {
491  return ctl_get_detail<M>(pop, name);
492  }
493 
505  template <typename M>
506  M
507  ctl_set(const std::string &name, M arg)
508  {
509  return ctl_set_detail(pop, name, arg);
510  }
511 
523  template <typename M>
524  M
525  ctl_exec(const std::string &name, M arg)
526  {
527  return ctl_exec_detail(pop, name, arg);
528  }
529 
530 #ifdef _WIN32
531 
541  template <typename M>
542  M
543  ctl_get(const std::wstring &name)
544  {
545  return ctl_get_detail<M>(pop, name);
546  }
547 
559  template <typename M>
560  M
561  ctl_set(const std::wstring &name, M arg)
562  {
563  return ctl_set_detail(pop, name, arg);
564  }
565 
577  template <typename M>
578  M
579  ctl_exec(const std::wstring &name, M arg)
580  {
581  return ctl_exec_detail(pop, name, arg);
582  }
583 #endif
584 
592  {
593  if (pop == nullptr)
594  throw pool_error("Invalid pool handle");
595 
596  persistent_ptr<T> root = pmemobj_root(this->pop, sizeof(T));
597  return root;
598  }
599 
600  POBJ_CPP_DEPRECATED persistent_ptr<T>
601  get_root()
602  {
603  return pool::root();
604  }
605 
618  static pool<T>
619  open(const std::string &path, const std::string &layout)
620  {
621  return pool<T>(pool_base::open(path, layout));
622  }
623 
640  static pool<T>
641  create(const std::string &path, const std::string &layout,
642  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
643  {
644  return pool<T>(pool_base::create(path, layout, size, mode));
645  }
646 
657  static int
658  check(const std::string &path, const std::string &layout)
659  {
660  return pool_base::check(path, layout);
661  }
662 
663 #ifdef _WIN32
664 
677  static pool<T>
678  open(const std::wstring &path, const std::wstring &layout)
679  {
680  return pool<T>(pool_base::open(path, layout));
681  }
682 
700  static pool<T>
701  create(const std::wstring &path, const std::wstring &layout,
702  std::size_t size = PMEMOBJ_MIN_POOL, mode_t mode = DEFAULT_MODE)
703  {
704  return pool<T>(pool_base::create(path, layout, size, mode));
705  }
706 
718  static int
719  check(const std::wstring &path, const std::wstring &layout)
720  {
721  return pool_base::check(path, layout);
722  }
723 #endif
724 };
725 
736 template <typename T>
737 T
738 ctl_get(const std::string &name)
739 {
740  return ctl_get_detail<T>(nullptr, name);
741 }
742 
754 template <typename T>
755 T
756 ctl_set(const std::string &name, T arg)
757 {
758  return ctl_set_detail(nullptr, name, arg);
759 }
760 
772 template <typename T>
773 T
774 ctl_exec(const std::string &name, T arg)
775 {
776  return ctl_exec_detail(nullptr, name, arg);
777 }
778 
779 #ifdef _WIN32
780 
790 template <typename T>
791 T
792 ctl_get(const std::wstring &name)
793 {
794  return ctl_get_detail<T>(nullptr, name);
795 }
796 
808 template <typename T>
809 T
810 ctl_set(const std::wstring &name, T arg)
811 {
812  return ctl_set_detail(nullptr, name, arg);
813 }
814 
826 template <typename T>
827 T
828 ctl_exec(const std::wstring &name, T arg)
829 {
830  return ctl_exec_detail(nullptr, name, arg);
831 }
832 #endif
833 
834 } /* namespace obj */
835 
836 } /* namespace pmem */
837 
838 #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:738
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::pool_base::persist
void persist(const persistent_ptr< Y > &ptr) noexcept
Performs persist operation on a given persistent object.
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:233
pmem::obj::pool::ctl_exec
M ctl_exec(const std::string &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:525
pmem::pool_error
Custom pool error class.
Definition: pexceptions.hpp:53
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:719
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:641
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:284
pmem::obj::pool::ctl_get
M ctl_get(const std::string &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:489
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:473
pmem::obj::pool::ctl_get
M ctl_get(const std::wstring &name)
Query libpmemobj state at pool scope.
Definition: pool.hpp:543
pmem::obj::pool::ctl_set
M ctl_set(const std::wstring &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:561
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:182
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:256
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:296
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:268
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:591
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:344
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:320
pmem::obj::pool_base::handle
PMEMobjpool * handle() noexcept
Gets the C style handle to the pool.
Definition: pool.hpp:398
pmem::obj::ctl_set
T ctl_set(const std::string &name, T arg)
Modify libpmemobj state at global scope.
Definition: pool.hpp:756
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:155
pmem::obj::pool::ctl_set
M ctl_set(const std::string &name, M arg)
Modify libpmemobj state at pool scope.
Definition: pool.hpp:507
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:206
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:431
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:619
pmem::obj::ctl_exec
T ctl_exec(const std::string &name, T arg)
Execute function at global scope.
Definition: pool.hpp:774
pmem::obj::pool::ctl_exec
M ctl_exec(const std::wstring &name, M arg)
Execute function at pool scope.
Definition: pool.hpp:579
std
A persistent version of concurrent hash map implementation Ref: https://arxiv.org/abs/1509....
Definition: concurrent_hash_map.hpp:75
pmem::obj::pool_base::flush
void flush(const p< Y > &prop) noexcept
Performs flush operation on a given pmem property.
Definition: pool.hpp:332
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:678
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:701
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:658