foedus::memory::SharedMemory Class Reference

Represents memory shared between processes. More...

Detailed Description

Represents memory shared between processes.

This class was initially a part of AlignedMemory, but we separated it out to reflect the special semantics of this type of memory.

Alloc/dealloc type

As this is a shared memory, there is only one choice unlike AlignedMemory. We always use shmget() with SHM_HUGETLB and shmat()/shmdt().

Pros/cons of System-V shmget()

We made this choice of share memory allocation API after trying all available options. The biggest pro of System-V shmget is that it does not need to mount a hugetlbfs for allocating hugepages. The cons are that it can't exceed kernel.shmmax and also we have to do a linux-dependent trick to reliably release the shared memory. For other choices, see the sections below.

Ownership

Every shared memory is allocated and owned by the master process. Forked/execed child processes, whether they are 'emulated' processes or not, do not have ownership thus should not release them at exit.

Moveable/Copiable

This object is NOT copiable. This object is moveable (the original object becomes null after the move).

Why not POSIX shm_open()

It can't use hugepages, period. shm_open is preferable because it's POSIX standard and also allows friendly naming to uniquefy the shared memory unlike shmget()'s integer ID. However, so far it doesn't allow hugepages and also we have to manually delete the file under /dev/shm.

Why not open() and mmap() with MAP_SHARED

It requires mounting hugetlbfs and also the user has to specify the path of the mounted file system in our configuration. This open/mmap is preferable because it is not affected by kernel.shmmax, which was an 'oversight' and might be corrected later, though. See the LWN article.

Why not mmap() with MAP_PRIVATE and MAP_SHARED

To allow sharing memory between arbitrary processes, we need non-private shared memory.

Debugging shared memories

ipcs -m ipcrm, etc etc.

Valgrind, shmat, and hugepages

Seems like valgrind has a bug on shmat with hugepages. I filed a bug report, not sure how it will be resolved. This causes all valgrind execution to fail on almost all testcases, crap. As a tentative work around, I check whether we are running on valgrind and, if so, get rid of SHM_HUGETLB from shmget call. Just for this reason, we have to include valgrind headers. gggrrrr.

See also

http://lwn.net/Articles/375096/

https://groups.google.com/forum/#!topic/fa.linux.kernel/OKplGDFf3EU

http://www.linuxquestions.org/questions/programming-9/shmctl-ipc_rmid-precludes-further-attachments-574636/

https://bugs.kde.org/show_bug.cgi?id=338995

Definition at line 92 of file shared_memory.hpp.

#include <shared_memory.hpp>

Public Member Functions
	SharedMemory () noexcept
	Empty constructor which allocates nothing. More...
	SharedMemory (const SharedMemory &other)=delete
SharedMemory &	operator= (const SharedMemory &other)=delete
	SharedMemory (SharedMemory &&other) noexcept
	Move constructor that steals the memory block from other. More...
SharedMemory &	operator= (SharedMemory &&other) noexcept
	Move assignment operator that steals the memory block from other. More...
	~SharedMemory ()
	Automatically releases the memory. More...
ErrorStack	alloc (const std::string &meta_path, uint64_t size, int numa_node, bool use_hugepages)
	Newly allocate a shared memory of given size on given NUMA node. More...
void	attach (const std::string &meta_path, bool use_hugepages)
	Attach an already-allocated shared memory so that this object points to the memory. More...
const std::string &	get_meta_path () const
	Returns the path of the meta file. More...
char *	get_block () const
	Returns the memory block. More...
int	get_shmid () const
	Returns the ID of this shared memory. More...
key_t	get_shmkey () const
	Returns the key of this shared memory. More...
pid_t	get_owner_pid () const
	If non-zero, it means the ID of the process that allocated the shared memory. More...
bool	is_null () const
	Returns if this object doesn't hold a valid memory block. More...
bool	is_owned () const
	Returns if this process owns this memory and is responsible to delete it. More...
uint64_t	get_size () const
	Returns the byte size of the memory block. More...
int	get_numa_node () const
	Where the physical memory is allocated. More...
void	mark_for_release ()
	Marks the shared memory as being removed so that it will be reclaimed when all processes detach it. More...
void	release_block ()
	Releases the memory block IF this process has an ownership. More...

Friends
std::ostream &	operator<< (std::ostream &o, const SharedMemory &v)

Constructor & Destructor Documentation

foedus::memory::SharedMemory::SharedMemory ( )

inlinenoexcept

Empty constructor which allocates nothing.

Definition at line 95 of file shared_memory.hpp.

    : size_(0), numa_node_(0), shmid_(0), shmkey_(0), owner_pid_(0), block_(CXX11_NULLPTR) {}

foedus::memory::SharedMemory::SharedMemory ( const SharedMemory &  other )

delete

foedus::memory::SharedMemory::SharedMemory ( SharedMemory &&  other )

noexcept

Move constructor that steals the memory block from other.

Definition at line 47 of file shared_memory.cpp.

                                                        : block_(nullptr) {
  *this = std::move(other);
}

foedus::memory::SharedMemory::~SharedMemory ( )

inline

Automatically releases the memory.

Definition at line 114 of file shared_memory.hpp.

References release_block().

{ release_block(); }

Here is the call graph for this function:

Member Function Documentation

ErrorStack foedus::memory::SharedMemory::alloc	(	const std::string &	meta_path,
		uint64_t	size,
		int	numa_node,
		bool	use_hugepages
	)

Newly allocate a shared memory of given size on given NUMA node.

This method should be called only at the master process.

Parameters

[in]	meta_path	This method will create a temporary meta file of this path and use it to generate a unique ID via ftok() and also put the size of the memory as content. It must be unique, for example '/tmp/foedus_shm_[master-PID]_vpool_[node-ID]'.
[in]	size	Byte size of the memory block. Actual allocation is at least of this size.
[in]	numa_node	Where the physical memory is allocated. Use for binding via libnuma.
[in]	use_hugepages	Whether to use hugepages.

Attention

When memory allocation fails for some reason (eg Out-Of-Memory), this method does NOT fail nor throws an exception. Instead, it sets the block_ NULL. So, the caller is responsible for checking it after construction.

Definition at line 67 of file shared_memory.cpp.

References ERROR_STACK_MSG, foedus::fs::exists(), foedus::debugging::get_rdtsc(), foedus::kErrorCodeSocShmAllocFailed, foedus::kRetOk, foedus::assorted::os_error(), and release_block().

Referenced by foedus::soc::SharedMemoryRepo::allocate_shared_memories().

                      {
  release_block();

  if (size % (1ULL << 21) != 0) {
    size = ((size >> 21) + 1ULL) << 21;
  }

  // create a meta file. we must first create it then generate key.
  // shmkey will change whenever we modify the file.
  if (fs::exists(fs::Path(meta_path))) {
    std::string msg = std::string("Shared memory meta file already exists:") + meta_path;
    return ERROR_STACK_MSG(kErrorCodeSocShmAllocFailed, msg.c_str());
  }
  std::ofstream file(meta_path, std::ofstream::binary);
  if (!file.is_open()) {
    std::string msg = std::string("Failed to create shared memory meta file:") + meta_path;
    return ERROR_STACK_MSG(kErrorCodeSocShmAllocFailed, msg.c_str());
  }

  // randomly generate shmkey. We initially used ftok(), but it occasionally gives lots of
  // conflicts for some reason, esp on aarch64. we just need some random number, so here
  // we use pid and CPU cycle.
  pid_t the_pid = ::getpid();
  uint64_t key64 = debugging::get_rdtsc() ^ the_pid;
  key_t the_key = (key64 >> 32) ^ key64;

  if (the_key == 0) {
    // rdtsc and getpid not working??
    std::string msg = std::string("Dubious shmkey");
    return ERROR_STACK_MSG(kErrorCodeSocShmAllocFailed, msg.c_str());
  }

  // Write out the size/node/shmkey of the shared memory in the meta file
  file.write(reinterpret_cast<char*>(&size), sizeof(size));
  file.write(reinterpret_cast<char*>(&numa_node), sizeof(numa_node));
  file.write(reinterpret_cast<char*>(&the_key), sizeof(key_t));
  file.flush();
  file.close();

  size_ = size;
  numa_node_ = numa_node;
  owner_pid_ = the_pid;
  meta_path_ = meta_path;
  shmkey_ = the_key;

  // if this is running under valgrind, we have to avoid using hugepages due to a bug in valgrind.
  // When we are running on valgrind, we don't care performance anyway. So shouldn't matter.
  if (RUNNING_ON_VALGRIND) {
    use_hugepages = false;
  }
  // see https://bugs.kde.org/show_bug.cgi?id=338995

  // Use libnuma's numa_set_preferred to initialize the NUMA node of the memory.
  // This is the only way to control numa allocation for shared memory.
  // mbind does nothing for shared memory.
  ScopedNumaPreferred numa_scope(numa_node, true);

  shmid_ = ::shmget(
    shmkey_,
    size_,
    IPC_CREAT | IPC_EXCL | S_IRUSR | S_IWUSR | (use_hugepages ? SHM_HUGETLB : 0));
  if (shmid_ == -1) {
    std::string msg = std::string("shmget() failed! size=") + std::to_string(size_)
      + std::string(", os_error=") + assorted::os_error() + std::string(", meta_path=") + meta_path;
    return ERROR_STACK_MSG(kErrorCodeSocShmAllocFailed, msg.c_str());
  }

  block_ = reinterpret_cast<char*>(::shmat(shmid_, nullptr, 0));

  if (block_ == reinterpret_cast<void*>(-1)) {
    ::shmctl(shmid_, IPC_RMID, nullptr);  // first thing. release it! before everything else.
    block_ = nullptr;
    std::stringstream msg;
    msg << "shmat alloc failed!" << *this << ", error=" << assorted::os_error();
    release_block();
    std::string str = msg.str();
    return ERROR_STACK_MSG(kErrorCodeSocShmAllocFailed, str.c_str());
  }

  std::memset(block_, 0, size_);  // see class comment for why we do this immediately
  // This memset takes a very long time due to the issue in linux kernel:
  // https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=8382d914ebf72092aa15cdc2a5dcedb2daa0209d
  // In linux 3.15 and later, this problem gets resolved and highly parallelizable.
  return kRetOk;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void foedus::memory::SharedMemory::attach	(	const std::string &	meta_path,
		bool	use_hugepages
	)

Attach an already-allocated shared memory so that this object points to the memory.

Parameters

[in]	meta_path	Path of the temporary meta file that contains memory size and shared memory ID.
[in]	use_hugepages	Whether to use hugepages.

Attention

If binding fails for some reason, this method does NOT fail nor throws an exception. Instead, it sets the block_ NULL. So, the caller is responsible for checking it after construction.

Definition at line 157 of file shared_memory.cpp.

References foedus::fs::exists(), foedus::assorted::os_error(), and release_block().

Referenced by foedus::soc::SharedMemoryRepo::attach_shared_memories().

                                                                        {
  release_block();
  if (!fs::exists(fs::Path(meta_path))) {
    std::cerr << "Shared memory meta file does not exist:" << meta_path << std::endl;
    return;
  }
  // the meta file contains the size of the shared memory
  std::ifstream file(meta_path, std::ifstream::binary);
  if (!file.is_open()) {
    std::cerr << "Failed to open shared memory meta file:" << meta_path << std::endl;
    return;
  }
  uint64_t shared_size = 0;
  int numa_node = 0;
  key_t the_key = 0;
  file.read(reinterpret_cast<char*>(&shared_size), sizeof(shared_size));
  file.read(reinterpret_cast<char*>(&numa_node), sizeof(numa_node));
  file.read(reinterpret_cast<char*>(&the_key), sizeof(key_t));
  file.close();

  // we always use hugepages, so it's at least 2MB
  if (shared_size < (1ULL << 21)) {
    std::cerr << "Failed to read size of shared memory from meta file:" << meta_path
      << ". It looks like:" << shared_size << std::endl;
    return;
  }
  if (the_key == 0) {
    std::cerr << "Failed to read shmkey from meta file:" << meta_path << std::endl;
    return;
  }

  size_ = shared_size;
  numa_node_ = numa_node;
  meta_path_ = meta_path;
  shmkey_ = the_key;
  owner_pid_ = 0;

  if (RUNNING_ON_VALGRIND) {
    use_hugepages = false;
  }
  shmid_ = ::shmget(shmkey_, size_, use_hugepages ? SHM_HUGETLB : 0);
  if (shmid_ == -1) {
    std::cerr << "shmget() attach failed! size=" << size_ << ", error=" << assorted::os_error()
      << std::endl;
    return;
  }

  block_ = reinterpret_cast<char*>(::shmat(shmid_, nullptr, 0));
  if (block_ == reinterpret_cast<void*>(-1)) {
    block_ = nullptr;
    std::cerr << "shmat attach failed!" << *this << ", error=" << assorted::os_error() << std::endl;
    release_block();
    return;
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

char* foedus::memory::SharedMemory::get_block ( ) const

inline

Returns the memory block.

Definition at line 144 of file shared_memory.hpp.

Referenced by foedus::soc::SharedMemoryRepo::allocate_shared_memories(), foedus::soc::SharedMemoryRepo::attach_shared_memories(), foedus::soc::SharedMemoryRepo::get_global_memory(), foedus::soc::SharedMemoryRepo::get_node_memory(), and foedus::memory::operator<<().

{ return block_; }

Here is the caller graph for this function:

const std::string& foedus::memory::SharedMemory::get_meta_path ( ) const

inline

Returns the path of the meta file.

Definition at line 142 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return meta_path_; }

Here is the caller graph for this function:

int foedus::memory::SharedMemory::get_numa_node ( ) const

inline

Where the physical memory is allocated.

Definition at line 158 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return numa_node_; }

Here is the caller graph for this function:

pid_t foedus::memory::SharedMemory::get_owner_pid ( ) const

inline

If non-zero, it means the ID of the process that allocated the shared memory.

Definition at line 150 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return owner_pid_; }

Here is the caller graph for this function:

int foedus::memory::SharedMemory::get_shmid ( ) const

inline

Returns the ID of this shared memory.

Definition at line 146 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return shmid_; }

Here is the caller graph for this function:

key_t foedus::memory::SharedMemory::get_shmkey ( ) const

inline

Returns the key of this shared memory.

Definition at line 148 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return shmkey_; }

Here is the caller graph for this function:

uint64_t foedus::memory::SharedMemory::get_size ( ) const

inline

Returns the byte size of the memory block.

Definition at line 156 of file shared_memory.hpp.

Referenced by foedus::memory::operator<<().

{ return size_; }

Here is the caller graph for this function:

bool foedus::memory::SharedMemory::is_null ( ) const

inline

Returns if this object doesn't hold a valid memory block.

Definition at line 152 of file shared_memory.hpp.

References CXX11_NULLPTR.

Referenced by foedus::soc::SharedMemoryRepo::attach_shared_memories(), and foedus::soc::SharedMemoryRepo::deallocate_shared_memories().

{ return block_ == CXX11_NULLPTR; }

Here is the caller graph for this function:

bool foedus::memory::SharedMemory::is_owned

(

)

const

Returns if this process owns this memory and is responsible to delete it.

Definition at line 63 of file shared_memory.cpp.

Referenced by foedus::memory::operator<<(), and release_block().

                                  {
  return owner_pid_ != 0 && owner_pid_ == ::getpid();
}

Here is the caller graph for this function:

void foedus::memory::SharedMemory::mark_for_release

(

)

Marks the shared memory as being removed so that it will be reclaimed when all processes detach it.

This is part of deallocation of shared memory in master process. After calling this method, no process can attach this shared memory. So, do not call this too early. However, on the other hand, do not call this too late. If the master process dies for an unexpected reason, the shared memory remains until next reboot. Call it as soon as child processes ack-ed that they have attached the memory or that there are some issues the master process should exit. This method is idempotent, meaning you can safely call this many times.

Definition at line 213 of file shared_memory.cpp.

Referenced by foedus::soc::SharedMemoryRepo::mark_for_release(), and release_block().

                                    {
  if (block_ != nullptr && shmid_ != 0) {
    // Some material says that Linux allows shmget even after shmctl(IPC_RMID), but it doesn't.
    // It allows shmat() after shmctl(IPC_RMID), but not shmget().
    // So we have to invoke IPC_RMID after all child processes acked.
    ::shmctl(shmid_, IPC_RMID, nullptr);
  }
}

Here is the caller graph for this function:

SharedMemory& foedus::memory::SharedMemory::operator= ( const SharedMemory &  other )

delete

SharedMemory & foedus::memory::SharedMemory::operator= ( SharedMemory &&  other )

noexcept

Move assignment operator that steals the memory block from other.

Definition at line 50 of file shared_memory.cpp.

References release_block().

                                                                   {
  release_block();
  meta_path_ = other.meta_path_;
  size_ = other.size_;
  numa_node_ = other.numa_node_;
  shmid_ = other.shmid_;
  shmkey_ = other.shmkey_;
  owner_pid_ = other.owner_pid_;
  block_ = other.block_;
  other.block_ = nullptr;
  return *this;
}

Here is the call graph for this function:

void foedus::memory::SharedMemory::release_block

(

)

Releases the memory block IF this process has an ownership.

Definition at line 222 of file shared_memory.cpp.

References is_owned(), mark_for_release(), foedus::assorted::os_error(), and foedus::fs::remove().

Referenced by alloc(), attach(), foedus::soc::SharedMemoryRepo::deallocate_shared_memories(), operator=(), and ~SharedMemory().

                                 {
  if (block_ != nullptr) {
    // mark the memory to be reclaimed
    if (is_owned()) {
      mark_for_release();
    }

    // Just detach it. as we already invoked shmctl(IPC_RMID) at beginning, linux will
    // automatically release it once the reference count reaches zero.
    int dt_ret = ::shmdt(block_);
    if (dt_ret == -1) {
      std::cerr << "shmdt() failed." << *this << ", error=" << assorted::os_error() << std::endl;
    }

    block_ = nullptr;

    // clean up meta file.
    if (is_owned()) {
      std::remove(meta_path_.c_str());
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  o, const SharedMemory &  v  )

friend

Definition at line 245 of file shared_memory.cpp.

                                                             {
  o << "<SharedMemory>";
  o << "<meta_path>" << v.get_meta_path() << "</meta_path>";
  o << "<size>" << v.get_size() << "</size>";
  o << "<owned>" << v.is_owned() << "</owned>";
  o << "<owner_pid>" << v.get_owner_pid() << "</owner_pid>";
  o << "<numa_node>" << v.get_numa_node() << "</numa_node>";
  o << "<shmid>" << v.get_shmid() << "</shmid>";
  o << "<shmkey>" << v.get_shmkey() << "</shmkey>";
  o << "<address>" << reinterpret_cast<uintptr_t>(v.get_block()) << "</address>";
  o << "</SharedMemory>";
  return o;
}

---

The documentation for this class was generated from the following files:

• /home/shino/foedus_code/foedus-core/include/foedus/memory/shared_memory.hpp
• /home/shino/foedus_code/foedus-core/src/foedus/memory/shared_memory.cpp