gdbsupport/ptid.h

   1 /* The ptid_t type and common functions operating on it.
   2
   3    Copyright (C) 1986-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef COMMON_PTID_H
  21 #define COMMON_PTID_H
  22
  23 /* The ptid struct is a collection of the various "ids" necessary for
  24    identifying the inferior process/thread being debugged.  This
  25    consists of the process id (pid), lightweight process id (lwp) and
  26    thread id (tid).  When manipulating ptids, the constructors,
  27    accessors, and predicates declared in this file should be used.  Do
  28    NOT access the struct ptid members directly.
  29
  30    process_stratum targets that handle threading themselves should
  31    prefer using the ptid.lwp field, leaving the ptid.tid field for any
  32    thread_stratum target that might want to sit on top.
  33 */
  34
  35 #include <functional>
  36 #include <string>
  37 #include "gdbsupport/common-types.h"
  38
  39 class ptid_t
  40 {
  41 public:
  42   using pid_type = int;
  43   using lwp_type = long;
  44   using tid_type = ULONGEST;
  45
  46   /* Must have a trivial defaulted default constructor so that the
  47      type remains POD.  */
  48   ptid_t () noexcept = default;
  49
  50   /* Make a ptid given the necessary PID, LWP, and TID components.
  51
  52      A ptid with only a PID (LWP and TID equal to zero) is usually used to
  53      represent a whole process, including all its lwps/threads.  */
  54
  55   explicit constexpr ptid_t (pid_type pid, lwp_type lwp = 0, tid_type tid = 0)
  56     : m_pid (pid), m_lwp (lwp), m_tid (tid)
  57   {}
  58
  59   /* Fetch the pid (process id) component from the ptid.  */
  60
  61   constexpr pid_type pid () const
  62   { return m_pid; }
  63
  64   /* Return true if the ptid's lwp member is non-zero.  */
  65
  66   constexpr bool lwp_p () const
  67   { return m_lwp != 0; }
  68
  69   /* Fetch the lwp (lightweight process) component from the ptid.  */
  70
  71   constexpr lwp_type lwp () const
  72   { return m_lwp; }
  73
  74   /* Return true if the ptid's tid member is non-zero.  */
  75
  76   constexpr bool tid_p () const
  77   { return m_tid != 0; }
  78
  79   /* Fetch the tid (thread id) component from a ptid.  */
  80
  81   constexpr tid_type tid () const
  82   { return m_tid; }
  83
  84   /* Return true if the ptid represents a whole process, including all its
  85      lwps/threads.  Such ptids have the form of (pid, 0, 0), with
  86      pid != -1.  */
  87
  88   constexpr bool is_pid () const
  89   {
  90     return (*this != make_null ()
  91             && *this != make_minus_one ()
  92             && m_lwp == 0
  93             && m_tid == 0);
  94   }
  95
  96   /* Compare two ptids to see if they are equal.  */
  97
  98   constexpr bool operator== (const ptid_t &other) const
  99   {
 100     return (m_pid == other.m_pid
 101             && m_lwp == other.m_lwp
 102             && m_tid == other.m_tid);
 103   }
 104
 105   /* Compare two ptids to see if they are different.  */
 106
 107   constexpr bool operator!= (const ptid_t &other) const
 108   {
 109     return !(*this == other);
 110   }
 111
 112   /* Return true if the ptid matches FILTER.  FILTER can be the wild
 113      card MINUS_ONE_PTID (all ptids match it); can be a ptid representing
 114      a process (ptid.is_pid () returns true), in which case, all lwps and
 115      threads of that given process match, lwps and threads of other
 116      processes do not; or, it can represent a specific thread, in which
 117      case, only that thread will match true.  The ptid must represent a
 118      specific LWP or THREAD, it can never be a wild card.  */
 119
 120   constexpr bool matches (const ptid_t &filter) const
 121   {
 122     return (/* If filter represents any ptid, it's always a match.  */
 123             filter == make_minus_one ()
 124             /* If filter is only a pid, any ptid with that pid
 125                matches.  */
 126             || (filter.is_pid () && m_pid == filter.pid ())
 127
 128             /* Otherwise, this ptid only matches if it's exactly equal
 129                to filter.  */
 130             || *this == filter);
 131   }
 132
 133   /* Return a string representation of the ptid.
 134
 135      This is only meant to be used in debug messages.  */
 136
 137   std::string to_string () const;
 138
 139   /* Make a null ptid.  */
 140
 141   static constexpr ptid_t make_null ()
 142   { return ptid_t (0, 0, 0); }
 143
 144   /* Make a minus one ptid.  */
 145
 146   static constexpr ptid_t make_minus_one ()
 147   { return ptid_t (-1, 0, 0); }
 148
 149 private:
 150   /* Process id.  */
 151   pid_type m_pid;
 152
 153   /* Lightweight process id.  */
 154   lwp_type m_lwp;
 155
 156   /* Thread id.  */
 157   tid_type m_tid;
 158 };
 159
 160 namespace std
 161 {
 162 template<>
 163 struct hash<ptid_t>
 164 {
 165   size_t operator() (const ptid_t &ptid) const
 166   {
 167     std::hash<long> long_hash;
 168
 169     return (long_hash (ptid.pid ())
 170             + long_hash (ptid.lwp ())
 171             + long_hash (ptid.tid ()));
 172   }
 173 };
 174 }
 175
 176 /* The null or zero ptid, often used to indicate no process. */
 177
 178 extern const ptid_t null_ptid;
 179
 180 /* The (-1,0,0) ptid, often used to indicate either an error condition
 181    or a "don't care" condition, i.e, "run all threads."  */
 182
 183 extern const ptid_t minus_one_ptid;
 184
 185 #endif /* COMMON_PTID_H */