[deliverable/binutils-gdb.git] / gdb / tid-parse.h

/* TID parsing for GDB, the GNU debugger.

   Copyright (C) 2015-2016 Free Software Foundation, Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef TID_PARSE_H
#define TID_PARSE_H

#include "cli/cli-utils.h"

struct thread_info;

/* Issue an invalid thread ID error, pointing at STRING, the invalid
   ID.  */
extern void ATTRIBUTE_NORETURN invalid_thread_id_error (const char *string);

/* Parse TIDSTR as a per-inferior thread ID, in either INF_NUM.THR_NUM
   or THR_NUM form.  In the latter case, the missing INF_NUM is filled
   in from the current inferior.  If ENDPTR is not NULL,
   parse_thread_id stores the address of the first character after the
   thread ID.  Either a valid thread is returned, or an error is
   thrown.  */
struct thread_info *parse_thread_id (const char *tidstr, const char **end);

/* The possible states of the tid range parser's state machine.  */
enum tid_range_state
{
  /* Parsing the inferior number.  */
  TID_RANGE_STATE_INFERIOR,

  /* Parsing the thread number or thread number range.  */
  TID_RANGE_STATE_THREAD_RANGE,
};

/* An object of this type is passed to tid_range_parser_get_tid.  It
   must be initialized by calling tid_range_parser_init.  This type is
   defined here so that it can be stack-allocated, but all members
   should be treated as opaque.  */
struct tid_range_parser
{
  /* What sub-component are we expecting.  */
  enum tid_range_state state;

  /* The string being parsed.  When parsing has finished, this points
     past the last parsed token.  */
  const char *string;

  /* The range parser state when we're parsing the thread number
     sub-component.  */
  struct get_number_or_range_state range_parser;

  /* Last inferior number returned.  */
  int inf_num;

  /* True if the TID last parsed was explicitly inferior-qualified.
     IOW, whether the spec specified an inferior number
     explicitly.  */
  int qualified;

  /* The inferior number to assume if the TID is not qualified.  */
  int default_inferior;
};

/* Initialize a tid_range_parser for use with
   tid_range_parser_get_tid.  TIDLIST is the string to be parsed.
   DEFAULT_INFERIOR is the inferior number to assume if a
   non-qualified thread ID is found.  */
extern void tid_range_parser_init (struct tid_range_parser *parser,
				   const char *tidlist,
				   int default_inferior);

/* Parse a thread ID or a thread range list.

   A range will be of the form

     <inferior_num>.<thread_number1>-<thread_number2>

   and will represent all the threads of inferior INFERIOR_NUM with
   number between THREAD_NUMBER1 and THREAD_NUMBER2, inclusive.
   <inferior_num> can also be omitted, as in

     <thread_number1>-<thread_number2>

   in which case GDB infers the inferior number from the default
   passed to the tid_range_parser_init function.

   This function is designed to be called iteratively.  While
   processing a thread ID range list, at each call it will return (in
   the INF_NUM and THR_NUM output parameters) the next thread ID in
   the range (irrespective of whether the thread actually exists).

   At the beginning of parsing a thread range, the char pointer
   PARSER->string will be advanced past <thread_number1> and left
   pointing at the '-' token.  Subsequent calls will not advance the
   pointer until the range is completed.  The call that completes the
   range will advance the pointer past <thread_number2>.

   This function advances through the input string for as long you
   call it.  Once the end of the input string is reached, a call to
   tid_range_parser_finished returns false (see below).

   E.g., with list: "1.2 3.4-6":

     1st call: *INF_NUM=1; *THR_NUM=2 (finished==0)
     2nd call: *INF_NUM=3; *THR_NUM=4 (finished==0)
     3rd call: *INF_NUM=3; *THR_NUM=5 (finished==0)
     4th call: *INF_NUM=3; *THR_NUM=6 (finished==1)

   Returns true if parsed a thread/range successfully, false
   otherwise.  */
extern int tid_range_parser_get_tid (struct tid_range_parser *parser,
				      int *inf_num, int *thr_num);

/* Like tid_range_parser_get_tid, but return a thread ID range per
   call, rather then a single thread ID.

   If the next element in the list is a single thread ID, then
   *THR_START and *THR_END are set to the same value.

   E.g.,. with list: "1.2 3.4-6"

     1st call: *INF_NUM=1; *THR_START=2; *THR_END=2 (finished==0)
     2nd call: *INF_NUM=3; *THR_START=4; *THR_END=6 (finished==1)

   Returns true if parsed a thread/range successfully, false
   otherwise.  */
extern int tid_range_parser_get_tid_range (struct tid_range_parser *parser,
					   int *inf_num,
					   int *thr_start, int *thr_end);

/* Returns non-zero if parsing has completed.  */
extern int tid_range_parser_finished (struct tid_range_parser *parser);

/* Return the string being parsed.  When parsing has finished, this
   points past the last parsed token.  */
const char *tid_range_parser_string (struct tid_range_parser *parser);

/* When parsing a range, advance past the final token in the range.  */
extern void tid_range_parser_skip (struct tid_range_parser *parser);

/* True if the TID last parsed was explicitly inferior-qualified.
   IOW, whether the spec specified an inferior number explicitly.  */
extern int tid_range_parser_qualified (struct tid_range_parser *parser);

/* Accept a string-form list of thread IDs such as is accepted by
   tid_range_parser_get_tid.  Return true if the INF_NUM.THR.NUM
   thread is in the list.  DEFAULT_INFERIOR is the inferior number to
   assume if a non-qualified thread ID is found in the list.

   By definition, an empty list includes all threads.  This is to be
   interpreted as typing a command such as "info threads" with no
   arguments.  */
extern int tid_is_in_list (const char *list, int default_inferior,
			   int inf_num, int thr_num);

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