gdb/tid-parse.h

   1 /* TID parsing for GDB, the GNU debugger.
   2
   3    Copyright (C) 2015-2016 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 TID_PARSE_H
  21 #define TID_PARSE_H
  22
  23 #include "cli/cli-utils.h"
  24
  25 struct thread_info;
  26
  27 /* Issue an invalid thread ID error, pointing at STRING, the invalid
  28    ID.  */
  29 extern void ATTRIBUTE_NORETURN invalid_thread_id_error (const char *string);
  30
  31 /* Parse TIDSTR as a per-inferior thread ID, in either INF_NUM.THR_NUM
  32    or THR_NUM form.  In the latter case, the missing INF_NUM is filled
  33    in from the current inferior.  If ENDPTR is not NULL,
  34    parse_thread_id stores the address of the first character after the
  35    thread ID.  Either a valid thread is returned, or an error is
  36    thrown.  */
  37 struct thread_info *parse_thread_id (const char *tidstr, const char **end);
  38
  39 /* The possible states of the tid range parser's state machine.  */
  40 enum tid_range_state
  41 {
  42   /* Parsing the inferior number.  */
  43   TID_RANGE_STATE_INFERIOR,
  44
  45   /* Parsing the thread number or thread number range.  */
  46   TID_RANGE_STATE_THREAD_RANGE,
  47
  48   /* Parsing a star wildcard thread range.  E.g., "1.*".  */
  49   TID_RANGE_STATE_STAR_RANGE,
  50 };
  51
  52 /* An object of this type is passed to tid_range_parser_get_tid.  It
  53    must be initialized by calling tid_range_parser_init.  This type is
  54    defined here so that it can be stack-allocated, but all members
  55    should be treated as opaque.  */
  56 struct tid_range_parser
  57 {
  58   /* What sub-component are we expecting.  */
  59   enum tid_range_state state;
  60
  61   /* The string being parsed.  When parsing has finished, this points
  62      past the last parsed token.  */
  63   const char *string;
  64
  65   /* The range parser state when we're parsing the thread number
  66      sub-component.  */
  67   struct get_number_or_range_state range_parser;
  68
  69   /* Last inferior number returned.  */
  70   int inf_num;
  71
  72   /* True if the TID last parsed was explicitly inferior-qualified.
  73      IOW, whether the spec specified an inferior number
  74      explicitly.  */
  75   int qualified;
  76
  77   /* The inferior number to assume if the TID is not qualified.  */
  78   int default_inferior;
  79 };
  80
  81 /* Initialize a tid_range_parser for use with
  82    tid_range_parser_get_tid.  TIDLIST is the string to be parsed.
  83    DEFAULT_INFERIOR is the inferior number to assume if a
  84    non-qualified thread ID is found.  */
  85 extern void tid_range_parser_init (struct tid_range_parser *parser,
  86                                    const char *tidlist,
  87                                    int default_inferior);
  88
  89 /* Parse a thread ID or a thread range list.
  90
  91    A range will be of the form
  92
  93      <inferior_num>.<thread_number1>-<thread_number2>
  94
  95    and will represent all the threads of inferior INFERIOR_NUM with
  96    number between THREAD_NUMBER1 and THREAD_NUMBER2, inclusive.
  97    <inferior_num> can also be omitted, as in
  98
  99      <thread_number1>-<thread_number2>
 100
 101    in which case GDB infers the inferior number from the default
 102    passed to the tid_range_parser_init function.
 103
 104    This function is designed to be called iteratively.  While
 105    processing a thread ID range list, at each call it will return (in
 106    the INF_NUM and THR_NUM output parameters) the next thread ID in
 107    the range (irrespective of whether the thread actually exists).
 108
 109    At the beginning of parsing a thread range, the char pointer
 110    PARSER->string will be advanced past <thread_number1> and left
 111    pointing at the '-' token.  Subsequent calls will not advance the
 112    pointer until the range is completed.  The call that completes the
 113    range will advance the pointer past <thread_number2>.
 114
 115    This function advances through the input string for as long you
 116    call it.  Once the end of the input string is reached, a call to
 117    tid_range_parser_finished returns false (see below).
 118
 119    E.g., with list: "1.2 3.4-6":
 120
 121      1st call: *INF_NUM=1; *THR_NUM=2 (finished==0)
 122      2nd call: *INF_NUM=3; *THR_NUM=4 (finished==0)
 123      3rd call: *INF_NUM=3; *THR_NUM=5 (finished==0)
 124      4th call: *INF_NUM=3; *THR_NUM=6 (finished==1)
 125
 126    Returns true if parsed a thread/range successfully, false
 127    otherwise.  */
 128 extern int tid_range_parser_get_tid (struct tid_range_parser *parser,
 129                                       int *inf_num, int *thr_num);
 130
 131 /* Like tid_range_parser_get_tid, but return a thread ID range per
 132    call, rather then a single thread ID.
 133
 134    If the next element in the list is a single thread ID, then
 135    *THR_START and *THR_END are set to the same value.
 136
 137    E.g.,. with list: "1.2 3.4-6"
 138
 139      1st call: *INF_NUM=1; *THR_START=2; *THR_END=2 (finished==0)
 140      2nd call: *INF_NUM=3; *THR_START=4; *THR_END=6 (finished==1)
 141
 142    Returns true if parsed a thread/range successfully, false
 143    otherwise.  */
 144 extern int tid_range_parser_get_tid_range (struct tid_range_parser *parser,
 145                                            int *inf_num,
 146                                            int *thr_start, int *thr_end);
 147
 148 /* Returns non-zero if processing a star wildcard (e.g., "1.*")
 149    range.  */
 150 extern int tid_range_parser_star_range (struct tid_range_parser *parser);
 151
 152 /* Returns non-zero if parsing has completed.  */
 153 extern int tid_range_parser_finished (struct tid_range_parser *parser);
 154
 155 /* Return the string being parsed.  When parsing has finished, this
 156    points past the last parsed token.  */
 157 const char *tid_range_parser_string (struct tid_range_parser *parser);
 158
 159 /* When parsing a range, advance past the final token in the range.  */
 160 extern void tid_range_parser_skip (struct tid_range_parser *parser);
 161
 162 /* True if the TID last parsed was explicitly inferior-qualified.
 163    IOW, whether the spec specified an inferior number explicitly.  */
 164 extern int tid_range_parser_qualified (struct tid_range_parser *parser);
 165
 166 /* Accept a string-form list of thread IDs such as is accepted by
 167    tid_range_parser_get_tid.  Return true if the INF_NUM.THR.NUM
 168    thread is in the list.  DEFAULT_INFERIOR is the inferior number to
 169    assume if a non-qualified thread ID is found in the list.
 170
 171    By definition, an empty list includes all threads.  This is to be
 172    interpreted as typing a command such as "info threads" with no
 173    arguments.  */
 174 extern int tid_is_in_list (const char *list, int default_inferior,
 175                            int inf_num, int thr_num);
 176
 177 #endif /* TID_PARSE_H */