blob: 52a78b131eac3bf2416356fb48a874efe59a9111 [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <stddef.h>
#include "base/base_export.h"
#include "base/logging.h"
#include "base/macros.h"
#include "base/memory/shared_memory_mapping.h"
#include "base/memory/unsafe_shared_memory_region.h"
#include "base/threading/thread_collision_warner.h"
#include "base/time/time.h"
#include "build/build_config.h"
#include <set>
// Linux (including Android) support the MADV_REMOVE argument with madvise()
// which has the behavior of reliably causing zero-fill-on-demand pages to
// be returned after a call. Here we define
// and Android to indicate that this type of behavior can be expected on
// those platforms. Note that madvise() will still be used on other POSIX
// platforms but doesn't provide the zero-fill-on-demand pages guarantee.
#if defined(OS_LINUX) || defined(OS_ANDROID)
namespace base {
namespace trace_event {
class MemoryAllocatorDump;
class ProcessMemoryDump;
} // namespace trace_event
// Platform abstraction for discardable shared memory.
// This class is not thread-safe. Clients are responsible for synchronizing
// access to an instance of this class.
class BASE_EXPORT DiscardableSharedMemory {
enum LockResult { SUCCESS, PURGED, FAILED };
// Create a new DiscardableSharedMemory object from an existing, open shared
// memory file. Memory must be locked.
explicit DiscardableSharedMemory(UnsafeSharedMemoryRegion region);
// Closes any open files.
virtual ~DiscardableSharedMemory();
// Creates and maps a locked DiscardableSharedMemory object with |size|.
// Returns true on success and false on failure.
bool CreateAndMap(size_t size);
// Maps the locked discardable memory into the caller's address space.
// Returns true on success, false otherwise.
bool Map(size_t size);
// Unmaps the discardable shared memory from the caller's address space.
// Unmapping won't unlock previously locked range.
// Returns true if successful; returns false on error or if the memory is
// not mapped.
bool Unmap();
// The actual size of the mapped memory (may be larger than requested).
size_t mapped_size() const { return mapped_size_; }
// Returns a duplicated shared memory region for this DiscardableSharedMemory
// object.
UnsafeSharedMemoryRegion DuplicateRegion() const {
return shared_memory_region_.Duplicate();
// Returns an ID for the shared memory region. This is ID of the mapped region
// consistent across all processes and is valid as long as the region is not
// unmapped.
const UnguessableToken& mapped_id() const {
return shared_memory_mapping_.guid();
// Locks a range of memory so that it will not be purged by the system.
// The range of memory must be unlocked. The result of trying to lock an
// already locked range is undefined. |offset| and |length| must both be
// a multiple of the page size as returned by GetPageSize().
// Passing 0 for |length| means "everything onward".
// Returns SUCCESS if range was successfully locked and the memory is still
// resident, PURGED if range was successfully locked but has been purged
// since last time it was locked and FAILED if range could not be locked.
// Locking can fail for two reasons; object might have been purged, our
// last known usage timestamp might be out of date. Last known usage time
// is updated to the actual last usage timestamp if memory is still resident
// or 0 if not.
LockResult Lock(size_t offset, size_t length);
// Unlock a previously successfully locked range of memory. The range of
// memory must be locked. The result of trying to unlock a not
// previously locked range is undefined.
// |offset| and |length| must both be a multiple of the page size as returned
// by GetPageSize().
// Passing 0 for |length| means "everything onward".
void Unlock(size_t offset, size_t length);
// Gets a pointer to the opened discardable memory space. Discardable memory
// must have been mapped via Map().
void* memory() const;
// Returns the last known usage time for DiscardableSharedMemory object. This
// may be earlier than the "true" usage time when memory has been used by a
// different process. Returns NULL time if purged.
Time last_known_usage() const { return last_known_usage_; }
// This returns true and sets |last_known_usage_| to 0 if
// DiscardableSharedMemory object was successfully purged. Purging can fail
// for two reasons; object might be locked or our last known usage timestamp
// might be out of date. Last known usage time is updated to |current_time|
// if locked or the actual last usage timestamp if unlocked. It is often
// necessary to call this function twice for the object to successfully be
// purged. First call, updates |last_known_usage_|. Second call, successfully
// purges the object using the updated |last_known_usage_|.
// Note: there is no guarantee that multiple calls to this function will
// successfully purge object. DiscardableSharedMemory object might be locked
// or another thread/process might be able to lock and unlock it in between
// each call.
bool Purge(Time current_time);
// Returns true if memory is still resident.
bool IsMemoryResident() const;
// Returns true if memory is locked.
bool IsMemoryLocked() const;
// Closes the open discardable memory segment.
// It is safe to call Close repeatedly.
void Close();
// For tracing: Creates ownership edge to the underlying shared memory dump
// which is cross process in the given |pmd|. |local_segment_dump| is the dump
// associated with the local discardable shared memory segment and |is_owned|
// is true when the current process owns the segment and the effective memory
// is assigned to the current process.
void CreateSharedMemoryOwnershipEdge(
trace_event::MemoryAllocatorDump* local_segment_dump,
trace_event::ProcessMemoryDump* pmd,
bool is_owned) const;
// LockPages/UnlockPages are platform-native discardable page management
// helper functions. Both expect |offset| to be specified relative to the
// base address at which |memory| is mapped, and that |offset| and |length|
// are page-aligned by the caller.
// Returns SUCCESS on platforms which do not support discardable pages.
static LockResult LockPages(const UnsafeSharedMemoryRegion& region,
size_t offset,
size_t length);
// UnlockPages() is a no-op on platforms not supporting discardable pages.
static void UnlockPages(const UnsafeSharedMemoryRegion& region,
size_t offset,
size_t length);
// Virtual for tests.
virtual Time Now() const;
UnsafeSharedMemoryRegion shared_memory_region_;
WritableSharedMemoryMapping shared_memory_mapping_;
size_t mapped_size_;
size_t locked_page_count_;
std::set<size_t> locked_pages_;
// Implementation is not thread-safe but still usable if clients are
// synchronized somehow. Use a collision warner to detect incorrect usage.
Time last_known_usage_;
} // namespace base