arena_activator.hpp

Go to the documentation of this file.

/* Flow-IPC: Shared Memory
 * Copyright 2023 Akamai Technologies, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy
 * of the License at
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing
 * permissions and limitations under the License. */
 
/// @file
#pragma once
 
#include "ipc/shm/stl/stl_fwd.hpp"
#include <flow/util/util.hpp>
 
namespace ipc::shm::stl
{
 
// Types.
 
/**
 * RAII-style class operating a stack-like notion of the given *thread*'s currently active
 * SHM-aware #Arena, so that Stateless_allocator knows which `Arena` is currently active w/r/t a given code context
 * operating on a SHM-stored container instance.
 *
 * In its ctor, it activates the given `Arena*`.  In its dtor it re-activates the `Arena*` active at ctor time
 * (or null if none was active).  Behavior is undefined if ctor and dtor are called from different threads.
 *
 * @see shm::stl namespace doc header for background.
 * @see Stateless_allocator, the main class template that Arena_activator helps one use.
 */
template<typename Arena_t>
class Arena_activator : private flow::util::Scoped_setter<Arena_t*>
{
public:
  // Types.
 
  /// Short-hand for the `Arena_t` type this activates/deactivates in the current thread of ctor/dtor.
  using Arena = Arena_t;
 
  // Constructors/destructor.
 
  /**
   * Activates the given #Arena.  `Stateless_allocator<T, Arena>` ops, as invoked by STL-compliant container
   * types parameterized on `Stateless_allocator<T, Arena>`, shall use that given arena for alloc/dealloc in the
   * calling thread until `*this` dtor is invoked.  The dtor shall restore the current `Arena*` (possibly null)
   * at time of entry to this ctor.
   *
   * Another `Arena_activator<Arena>` can be used to activate/deactivate another #Arena in stack-like
   * fashion.
   *
   * @param new_arena_not_null
   *        The #Arena to activate.  Must not be null (else behavior undefined/assertion may trip).
   */
  explicit Arena_activator(Arena* new_arena_not_null);
 
  /// See ctor.  This undoes what that did.
  ~Arena_activator();
 
  // Methods.
 
  /**
   * Returns the active arena, as understood by `Stateless_allocator<T, Arena>` (any `T`) at this point in the calling
   * thread.  This is generally used by Stateless_allocator itself; but it is publicly exposed also, as it may
   * be of interest.
   *
   * @return See above.  Note this may be null.
   */
  static Arena* this_thread_active_arena();
 
private:
  // Data.
 
  /**
   * See this_thread_active_arena().  The key point is it is thread-local and a separate object per distinct #Arena
   * type.
   */
  static thread_local Arena* s_this_thread_active_arena;
}; // class Arena_activator
 
// Template static initializers.
 
template<typename Arena_t>
thread_local Arena_t* Arena_activator<Arena_t>::s_this_thread_active_arena{nullptr};
 
// Template implementations.
 
template<typename Arena_t>
Arena_activator<Arena_t>::Arena_activator(Arena* new_arena_not_null) :
  flow::util::Scoped_setter<Arena*>(&s_this_thread_active_arena, std::move(new_arena_not_null))
{
  assert(this_thread_active_arena()
         && "Per contract do not activate null.  Current arena is null only in the outside scope.");
}
 
template<typename Arena_t>
Arena_activator<Arena_t>::~Arena_activator() = default; // Only declared to officially document it.
 
template<typename Arena_t>
Arena_t* Arena_activator<Arena_t>::this_thread_active_arena() // Static.
{
  return s_this_thread_active_arena;
}
 
} // namespace ipc::shm::stl