Channel.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2000-2005, 2013, 2018, 2020, 2023, 2026 Carlo Wood
// SPDX-License-Identifier: MIT
 
#pragma once

 
#ifndef LIBCWD_CLASS_CHANNEL_H
#define LIBCWD_CLASS_CHANNEL_H
 
#include "control_flag.h"
#include "max_label_len.h"
#include "private/ThreadSpecificData.h"
#include "libcwd/config.h"
 
#include <atomic>
 
namespace libcwd {
 
namespace _private_ {
struct DebugChannels;
struct ChannelSetsWat;
} // namespace _private_

 
class Channel
{
 private:
  int index_;
  // Assigned during initialization before this channel is made visible to other threads.
  // A unique id that is used as index into the TSD array `off_cnt_array`.
 
  char label_[max_label_len + 1]; // +1 for zero termination.
                                  // Initialized before this channel is made visible to other threads and read-only
                                  // afterward. A reference name for the represented debug channel This label will be
                                  // printed in front of each output written to this debug channel.
 
  bool initialized_;
  // Written during initialization before this channel is made visible to other threads.
  // Set to true when initialized.
 
  static Channel const off_channel;
  // Channel that is always off.
 
 public:
  //---------------------------------------------------------------------------
  // Constructor
  //
 
  // MT: All channel objects must be global so that `initialized_` is false
  //     at the start of the program and initialization occurs before other threads
  //     share the object.
  explicit Channel(char const* label, bool add_to_channel_list = true);
 
  // MT: May only be called from the constructors of global objects (or single threaded functions).
  void NS_initialize(char const* label, LIBCWD_TSD_PARAM, bool add_to_channel_list);
  // Force initialization in case the constructor of this global object
  // wasn't called yet. Does nothing when the object was already initialized.
 
 private:
  // MT: Take advantage of the public debug-channel registry write lock to prevent
  // simultaneous access to ChannelSets::next_index_ in the case of simultaneously
  // dlopen-loaded libraries and to create a happens-before edge between the write-once
  // and potential reads of this class members by other threads.
  friend struct _private_::DebugChannels;
  void initialize(_private_::ChannelSetsWat wat, char const* label, size_t label_len);
 
 public:
  //---------------------------------------------------------------------------
  // Manipulators
  //
 
  void off();
  void on();
 
  struct OnOffState
  {
    int off_cnt;
  };
 
  void force_on(OnOffState& state, char const* label);
  void restore(OnOffState const& state);
 
  Channel const& operator()(bool cond) const { return cond ? *this : off_channel; }
 
 public:
  //---------------------------------------------------------------------------
  // Accessors
  //
 
  int index() const { return index_; }
  char const* get_label() const;
  bool is_on() const;
  bool is_on(LIBCWD_TSD_PARAM) const;
};
 
} // namespace libcwd
 
#endif // LIBCWD_CLASS_CHANNEL_H