folly::MemoryMapping Class Reference

#include <MemoryMapping.h>

Inheritance diagram for folly::MemoryMapping:

Classes
struct	Options

Public Types
enum	LockMode { LockMode::TRY_LOCK, LockMode::MUST_LOCK }
enum	AnonymousType { kAnonymous }

Public Member Functions
	MemoryMapping (AnonymousType, off_t length, Options options=Options())
	MemoryMapping (File file, off_t offset=0, off_t length=-1, Options options=Options())
	MemoryMapping (const char *name, off_t offset=0, off_t length=-1, Options options=Options())
	MemoryMapping (int fd, off_t offset=0, off_t length=-1, Options options=Options())
	MemoryMapping (MemoryMapping &&) noexcept
	~MemoryMapping ()
MemoryMapping &	operator= (MemoryMapping)
void	swap (MemoryMapping &other) noexcept
bool	mlock (LockMode lock)
void	munlock (bool dontneed=false)
void	hintLinearScan ()
void	advise (int advice) const
void	advise (int advice, size_t offset, size_t length) const
template<class T >
Range< const T * >	asRange () const
ByteRange	range () const
template<class T >
Range< T * >	asWritableRange () const
MutableByteRange	writableRange () const
StringPiece	data () const
bool	mlocked () const
int	fd () const

Static Public Member Functions
static Options	writable ()

Private Types
enum	InitFlags { kGrow = 1 << 0, kAnon = 1 << 1 }

Private Member Functions
	MemoryMapping ()
void	init (off_t offset, off_t length)

Private Attributes
File	file_
void *	mapStart_ = nullptr
off_t	mapLength_ = 0
Options	options_
bool	locked_ = false
MutableByteRange	data_

Detailed Description

Maps files in memory (read-only).

Author

Tudor Bosman (tudor.nosp@m.b@fb.nosp@m..com)

Definition at line 32 of file MemoryMapping.h.

Member Enumeration Documentation

enum folly::MemoryMapping::AnonymousType

Enumerator
kAnonymous

Definition at line 123 of file MemoryMapping.h.

                     {
    kAnonymous,
  };

enum folly::MemoryMapping::InitFlags

private

Enumerator
kGrow
kAnon

Definition at line 238 of file MemoryMapping.h.

                 {
    kGrow = 1 << 0,
    kAnon = 1 << 1,
  };

enum folly::MemoryMapping::LockMode

strong

Lock the pages in memory? TRY_LOCK = try to lock, log warning if permission denied MUST_LOCK = lock, fail assertion if permission denied.

Enumerator
TRY_LOCK
MUST_LOCK

Definition at line 39 of file MemoryMapping.h.

                      {
    TRY_LOCK,
    MUST_LOCK,
  };

Constructor & Destructor Documentation

folly::MemoryMapping::MemoryMapping	(	AnonymousType	,
		off_t	length,
		Options	options = Options()
	)

Create an anonymous mapping.

Definition at line 92 of file MemoryMapping.cpp.

References folly::getHugePageSizeForDevice(), and init().

    : options_(std::move(options)) {
  init(0, length);
}

folly::MemoryMapping::MemoryMapping ( File  file, off_t  offset = 0, off_t  length = -1, Options  options = Options()  )

explicit

Definition at line 64 of file MemoryMapping.cpp.

References file_, and init().

    : file_(std::move(file)), options_(std::move(options)) {
  CHECK(file_);
  init(offset, length);
}

folly::MemoryMapping::MemoryMapping ( const char *  name, off_t  offset = 0, off_t  length = -1, Options  options = Options()  )

explicit

Definition at line 74 of file MemoryMapping.cpp.

    : MemoryMapping(
          File(name, options.writable ? O_RDWR : O_RDONLY),
          offset,
          length,
          options) {}

folly::MemoryMapping::MemoryMapping ( int  fd, off_t  offset = 0, off_t  length = -1, Options  options = Options()  )

explicit

Definition at line 85 of file MemoryMapping.cpp.

    : MemoryMapping(File(fd), offset, length, options) {}

folly::MemoryMapping::MemoryMapping ( MemoryMapping &&  other )

noexcept

Definition at line 60 of file MemoryMapping.cpp.

References swap().

                                                           {
  swap(other);
}

folly::MemoryMapping::~MemoryMapping

(

)

Definition at line 329 of file MemoryMapping.cpp.

References folly::FATAL, folly::format(), mapLength_, mapStart_, options_, and folly::MemoryMapping::Options::pageSize.

                              {
  if (mapLength_) {
    size_t amountSucceeded = 0;
    if (!memOpInChunks(
            ::munmap,
            mapStart_,
            size_t(mapLength_),
            options_.pageSize,
            amountSucceeded)) {
      PLOG(FATAL) << folly::format(
          "munmap({}) failed at {}", mapLength_, amountSucceeded);
    }
  }
}

folly::MemoryMapping::MemoryMapping ( )

private

Referenced by fd().

Member Function Documentation

void folly::MemoryMapping::advise

(

int

advice

)

const

Advise the kernel about memory access.

Definition at line 344 of file MemoryMapping.cpp.

References mapLength_.

Referenced by hintLinearScan(), and folly::TEST().

                                           {
  advise(advice, 0, size_t(mapLength_));
}

void folly::MemoryMapping::advise	(	int	advice,
		size_t	offset,
		size_t	length
	)		const

Definition at line 348 of file MemoryMapping.cpp.

References mapLength_, mapStart_, options_, folly::MemoryMapping::Options::pageSize, and folly::WARNING.

                                                                         {
  CHECK_LE(offset + length, size_t(mapLength_))
      << " offset: " << offset << " length: " << length
      << " mapLength_: " << mapLength_;

  // Include the entire start page: round down to page boundary.
  const auto offMisalign = offset % options_.pageSize;
  offset -= offMisalign;
  length += offMisalign;

  // Round the last page down to page boundary.
  if (offset + length != size_t(mapLength_)) {
    length -= length % options_.pageSize;
  }

  if (length == 0) {
    return;
  }

  char* mapStart = static_cast<char*>(mapStart_) + offset;
  PLOG_IF(WARNING, ::madvise(mapStart, length, advice)) << "madvise";
}

template<class T >

Range<const T*> folly::MemoryMapping::asRange ( ) const

inline

A bitwise cast of the mapped bytes as range of values. Only intended for use with POD or in-place usable types.

Definition at line 187 of file MemoryMapping.h.

References count, folly::Range< Iter >::data(), data_, folly::Range< Iter >::size(), and folly::T.

Referenced by folly::TEST().

                                  {
    size_t count = data_.size() / sizeof(T);
    return Range<const T*>(
        static_cast<const T*>(static_cast<const void*>(data_.data())), count);
  }

template<class T >

Range<T*> folly::MemoryMapping::asWritableRange ( ) const

inline

A bitwise cast of the mapped bytes as range of mutable values. Only intended for use with POD or in-place usable types.

Definition at line 205 of file MemoryMapping.h.

References count, folly::Range< Iter >::data(), data_, options_, folly::Range< Iter >::size(), folly::T, and folly::MemoryMapping::Options::writable.

Referenced by folly::TEST().

                                    {
    DCHECK(options_.writable); // you'll segfault anyway...
    size_t count = data_.size() / sizeof(T);
    return Range<T*>(static_cast<T*>(static_cast<void*>(data_.data())), count);
  }

StringPiece folly::MemoryMapping::data ( ) const

inline

Return the memory area where the file was mapped. Deprecated; use range() instead.

Definition at line 223 of file MemoryMapping.h.

Referenced by folly::TEST().

                           {
    return asRange<const char>();
  }

int folly::MemoryMapping::fd ( ) const

inline

Definition at line 231 of file MemoryMapping.h.

References folly::File::fd(), file_, and MemoryMapping().

                 {
    return file_.fd();
  }

void folly::MemoryMapping::hintLinearScan

(

)

Hint that these pages will be scanned linearly. madvise(MADV_SEQUENTIAL)

Definition at line 325 of file MemoryMapping.cpp.

References advise().

Referenced by folly::mmapFileCopy().

                                   {
  advise(MADV_SEQUENTIAL);
}

void folly::MemoryMapping::init ( off_t  offset, off_t  length  )

private

Definition at line 113 of file MemoryMapping.cpp.

References addr, folly::MemoryMapping::Options::address, data_, folly::File::fd(), file_, folly::MemoryMapping::Options::grow, MAP_POPULATE, mapLength_, mapStart_, min, options_, folly::MemoryMapping::Options::pageSize, folly::MemoryMapping::Options::prefault, folly::MemoryMapping::Options::readable, folly::Range< Iter >::reset(), folly::MemoryMapping::Options::shared, folly::size(), start, and folly::MemoryMapping::Options::writable.

Referenced by MemoryMapping().

                                                   {
  const bool grow = options_.grow;
  const bool anon = !file_;
  CHECK(!(grow && anon));

  off_t& pageSize = options_.pageSize;

  struct stat st;

  // On Linux, hugetlbfs file systems don't require ftruncate() to grow the
  // file, and (on kernels before 2.6.24) don't even allow it. Also, the file
  // size is always a multiple of the page size.
  bool autoExtend = false;

  if (!anon) {
    // Stat the file
    CHECK_ERR(fstat(file_.fd(), &st));

    if (pageSize == 0) {
      getDeviceOptions(st.st_dev, pageSize, autoExtend);
    }
  } else {
    DCHECK(!file_);
    DCHECK_EQ(offset, 0);
    CHECK_EQ(pageSize, 0);
    CHECK_GE(length, 0);
  }

  if (pageSize == 0) {
    pageSize = off_t(sysconf(_SC_PAGESIZE));
  }

  CHECK_GT(pageSize, 0);
  CHECK_EQ(pageSize & (pageSize - 1), 0); // power of two
  CHECK_GE(offset, 0);

  // Round down the start of the mapped region
  off_t skipStart = offset % pageSize;
  offset -= skipStart;

  mapLength_ = length;
  if (mapLength_ != -1) {
    mapLength_ += skipStart;

    // Round up the end of the mapped region
    mapLength_ = (mapLength_ + pageSize - 1) / pageSize * pageSize;
  }

  off_t remaining = anon ? length : st.st_size - offset;

  if (mapLength_ == -1) {
    length = mapLength_ = remaining;
  } else {
    if (length > remaining) {
      if (grow) {
        if (!autoExtend) {
          PCHECK(0 == ftruncate(file_.fd(), offset + length))
              << "ftruncate() failed, couldn't grow file to "
              << offset + length;
          remaining = length;
        } else {
          // Extend mapping to multiple of page size, don't use ftruncate
          remaining = mapLength_;
        }
      } else {
        length = remaining;
      }
    }
    if (mapLength_ > remaining) {
      mapLength_ = remaining;
    }
  }

  if (length == 0) {
    mapLength_ = 0;
    mapStart_ = nullptr;
  } else {
    int flags = options_.shared ? MAP_SHARED : MAP_PRIVATE;
    if (anon) {
      flags |= MAP_ANONYMOUS;
    }
    if (options_.prefault) {
      flags |= MAP_POPULATE;
    }

    // The standard doesn't actually require PROT_NONE to be zero...
    int prot = PROT_NONE;
    if (options_.readable || options_.writable) {
      prot =
          ((options_.readable ? PROT_READ : 0) |
           (options_.writable ? PROT_WRITE : 0));
    }

    unsigned char* start = static_cast<unsigned char*>(mmap(
        options_.address, size_t(mapLength_), prot, flags, file_.fd(), offset));
    PCHECK(start != MAP_FAILED)
        << " offset=" << offset << " length=" << mapLength_;
    mapStart_ = start;
    data_.reset(start + skipStart, size_t(length));
  }
}

bool folly::MemoryMapping::mlock

(

LockMode

lock

)

Lock the pages in memory

Definition at line 269 of file MemoryMapping.cpp.

References folly::FATAL, folly::format(), locked_, mapLength_, mapStart_, munlock(), options_, folly::MemoryMapping::Options::pageSize, TRY_LOCK, and folly::WARNING.

Referenced by folly::TEST().

                                       {
  size_t amountSucceeded = 0;
  locked_ = memOpInChunks(
      ::mlock,
      mapStart_,
      size_t(mapLength_),
      options_.pageSize,
      amountSucceeded);
  if (locked_) {
    return true;
  }

  auto msg =
      folly::format("mlock({}) failed at {}", mapLength_, amountSucceeded);
  if (lock == LockMode::TRY_LOCK && errno == EPERM) {
    PLOG(WARNING) << msg;
  } else if (lock == LockMode::TRY_LOCK && errno == ENOMEM) {
    VLOG(1) << msg;
  } else {
    PLOG(FATAL) << msg;
  }

  // only part of the buffer was mlocked, unlock it back
  if (!memOpInChunks(
          ::munlock,
          mapStart_,
          amountSucceeded,
          options_.pageSize,
          amountSucceeded)) {
    PLOG(WARNING) << "munlock()";
  }

  return false;
}

bool folly::MemoryMapping::mlocked ( ) const

inline

Definition at line 227 of file MemoryMapping.h.

References locked_.

Referenced by folly::TEST().

                       {
    return locked_;
  }

void folly::MemoryMapping::munlock

(

bool

dontneed = false

)

Unlock the pages. If dontneed is true, the kernel is instructed to release these pages (per madvise(MADV_DONTNEED)).

Definition at line 304 of file MemoryMapping.cpp.

References locked_, mapLength_, mapStart_, options_, folly::MemoryMapping::Options::pageSize, and folly::WARNING.

Referenced by mlock().

                                         {
  if (!locked_) {
    return;
  }

  size_t amountSucceeded = 0;
  if (!memOpInChunks(
          ::munlock,
          mapStart_,
          size_t(mapLength_),
          options_.pageSize,
          amountSucceeded)) {
    PLOG(WARNING) << "munlock()";
  }
  if (mapLength_ && dontneed &&
      ::madvise(mapStart_, size_t(mapLength_), MADV_DONTNEED)) {
    PLOG(WARNING) << "madvise()";
  }
  locked_ = false;
}

MemoryMapping & folly::MemoryMapping::operator=

(

MemoryMapping

other

)

Definition at line 371 of file MemoryMapping.cpp.

References swap().

                                                           {
  swap(other);
  return *this;
}

ByteRange folly::MemoryMapping::range ( ) const

inline

A range of bytes mapped by this mapping.

Definition at line 196 of file MemoryMapping.h.

References data_.

Referenced by folly::mmapFileCopy(), and folly::RecordIOReader::seek().

                          {
    return data_;
  }

void folly::MemoryMapping::swap ( MemoryMapping &  other )

noexcept

Definition at line 376 of file MemoryMapping.cpp.

References data_, file_, locked_, mapLength_, mapStart_, options_, and folly::swap().

Referenced by MemoryMapping(), and operator=().

                                                      {
  using std::swap;
  swap(this->file_, other.file_);
  swap(this->mapStart_, other.mapStart_);
  swap(this->mapLength_, other.mapLength_);
  swap(this->options_, other.options_);
  swap(this->locked_, other.locked_);
  swap(this->data_, other.data_);
}

static Options folly::MemoryMapping::writable ( )

inlinestatic

Definition at line 119 of file MemoryMapping.h.

References folly::MemoryMapping::Options::setGrow(), and folly::MemoryMapping::Options::setWritable().

Referenced by folly::mmapFileCopy(), folly::MemoryMapping::Options::setWritable(), and folly::TEST().

                            {
    return Options().setWritable(true).setGrow(true);
  }

MutableByteRange folly::MemoryMapping::writableRange ( ) const

inline

A range of mutable bytes mapped by this mapping.

Definition at line 214 of file MemoryMapping.h.

References data_, options_, and folly::MemoryMapping::Options::writable.

                                         {
    DCHECK(options_.writable); // you'll segfault anyway...
    return data_;
  }

Member Data Documentation

MutableByteRange folly::MemoryMapping::data_

private

Definition at line 249 of file MemoryMapping.h.

Referenced by asRange(), asWritableRange(), init(), range(), swap(), and writableRange().

File folly::MemoryMapping::file_

private

Definition at line 244 of file MemoryMapping.h.

Referenced by fd(), init(), MemoryMapping(), and swap().

bool folly::MemoryMapping::locked_ = false

private

Definition at line 248 of file MemoryMapping.h.

Referenced by mlock(), mlocked(), munlock(), and swap().

off_t folly::MemoryMapping::mapLength_ = 0

private

Definition at line 246 of file MemoryMapping.h.

Referenced by advise(), init(), mlock(), munlock(), swap(), and ~MemoryMapping().

void* folly::MemoryMapping::mapStart_ = nullptr

private

Definition at line 245 of file MemoryMapping.h.

Referenced by advise(), init(), mlock(), munlock(), swap(), and ~MemoryMapping().

Options folly::MemoryMapping::options_

private

Definition at line 247 of file MemoryMapping.h.

Referenced by advise(), asWritableRange(), init(), mlock(), munlock(), swap(), writableRange(), and ~MemoryMapping().

---

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

• proxygen/folly/folly/system/MemoryMapping.h
• proxygen/folly/folly/system/MemoryMapping.cpp