123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050 |
- /* Interface between GCC C++ FE and GDB -*- c -*-
- Copyright (C) 2014-2022 Free Software Foundation, Inc.
- This file is part of GCC.
- 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/>. */
- /* Push namespace NAME as the current binding level, to which
- newly-introduced decls will be bound. An empty string identifies
- the global namespace, whereas NULL identifies an anonymous
- namespace. A namespace named NAME is created in the current scope,
- if needed.
- If the newly-created namespace is to be an inline namespace, see
- make_namespace_inline. */
- GCC_METHOD1 (int /* bool */, push_namespace,
- const char *) /* Argument NAME. */
- /* Push TYPE as the current binding level, making its members visible
- for name lookup. The current scope before the call must be the
- scope in which the class was declared. This should be used if the
- definition of a class is already finished, but one wishes to define
- a nested class, or to enter the scope of one of its member
- functions. */
- GCC_METHOD1 (int /* bool */, push_class,
- gcc_type) /* Argument TYPE. */
- /* Push FUNCTION_DECL as the current (empty) binding level (see
- reactivate_decl). The current enclosing scope before the call must
- be the scope in which the function was declared. */
- GCC_METHOD1 (int /* bool */, push_function,
- gcc_decl) /* Argument FUNCTION_DECL. */
- /* Make DECL visible (again?) within SCOPE. When SCOPE is NULL, it
- means the current scope; if it is not NULL, it must name a function
- that is currently active, even if not at the top of the binding
- chain.
- This function can be used to make e.g. a global function or
- variable visible in a namespace or local scope (overriding another
- enclosing definition of the same name), but its most common
- expected use of this primitive, that gives it its name, is to make
- declarations visible again after reentering a function scope,
- because when a function is entered with push_function, that does
- NOT make any of the declarations nested in it visible for name
- lookup.
- There is a reason/excuse for that: unlike namespaces and classes,
- G++ doesn't ever have to reenter function scopes, so its name
- resolution infrastructure is not prepared to do that. But wait,
- there is also a good use for this apparent limitation: a function
- may contain multiple scopes (blocks), and the name may be bound to
- different symbols in each of these scopes. With this interface, as
- we reenter a function scope, we may choose which symbols to make
- visible for the code snippet, or, if there could be template
- functions in local scopes, for unresolved names in nested template
- class default arguments, or in nested template function signatures.
- As for making a local declaration visible for the code snippet,
- there are two possibilities: a) introduce it upfront, while
- entering the scope for the user expression (see the enter_scope
- callback, called by g++ when encountering the push_user_expression
- pragma), which might save some scope switching and reactivate_decl
- (though this can't be helped if some declarations have to be
- introduced and discarded, because of multiple definitions of the
- same name in different scopes within a function: they have to be
- defined in discriminator order); or b) introduce it when its name
- is looked up, entering the scope, introducing the declaration,
- leaving the scope, and then reactivating the declaration in its
- local scope.
- Here's some more detail on how reactivate_decl works. Say there's
- a function foo whose body looks like this:
- {
- {
- // point 1
- class c {} o __attribute__ ((__used__)); // c , o
- }
- struct c {
- void f() {
- // point 2
- }
- } o __attribute__ ((__used__)); // c_0, o_0
- {
- class c {} p __attribute__ ((__used__)); // c_1, p
- // point 3
- o.f();
- }
- }
- When we are about to define class c at point 1, we enter the
- function foo scope, and since no symbols are visible at point 1, we
- proceed to declare class c. We may then define the class right
- away, or, if we leave the function scope, and we later wish to
- define it, or to define object o, we can reenter the scope and just
- use the previously-obtained gcc_decl to define the class, without
- having to reactivate the declaration.
- Now, if we are to set up the binding context for point 2, we have
- to define c_0::f, and in order to do so, we have to declare and
- define c_0. Before we can declare c_0, we MUST at least declare c.
- As a general rule, before we can declare or define any local name
- with a discriminator, we have to at least declare any other
- occurrences of the same name in the same enclosing entity with
- lower or absent discriminator.
- So, we declare c, then we leave the function scope and reenter it
- so as to declare c_0 (also with name "c", which is why we have to
- leave and reenter the function scope, otherwise we would get an
- error because of the duplicate definition; g++ will assign a
- discriminator because it still remembers there was an earlier
- declaration of c_0 within the function, it's just no longer in
- scope), then we can define c_0, including its member function f.
- Likewise, if we wish to define o_0, we have to define o first. If
- we wish to declare (and maybe then define) c_1, we have to at least
- declare (c and then) c_0 first.
- Then, as we set up the binding context to compile a code snippet at
- point 3, we may choose to activate c_1, o_0 and p upfront,
- declaring and discarding c, c_0 and o, and then reentering the
- funciton scope to declare c_1, o_0 and p; or we can wait for oracle
- lookups of c, o or p. If c is looked up, and the debugger resolves
- c in the scope to c_1, it is expected to enter the function scope
- from the top level, declare c, leave it, reenter it, declare c_0,
- leave it, reenter it, declare c_1, leave it, and then reactivate
- c_1 in the function scope. If c_1 is needed as a complete type,
- the definition may be given right after the declaration, or the
- scope will have to be reentered in order to define the class.
- . If the code snippet is at point 2, we don't need to (re)activate
- any declaration: nothing from any local scope is visible. Just
- entering the scope of the class containing member function f
- reactivates the names of its members, including the class name
- itself. */
- GCC_METHOD2 (int /* bool */, reactivate_decl,
- gcc_decl, /* Argument DECL. */
- gcc_decl) /* Argument SCOPE. */
- /* Pop the namespace last entered with push_namespace, or class last
- entered with push_class, or function last entered with
- push_function, restoring the binding level in effect before the
- matching push_* call. */
- GCC_METHOD0 (int /* bool */, pop_binding_level)
- /* Return the NAMESPACE_DECL, TYPE_DECL or FUNCTION_DECL of the
- binding level that would be popped by pop_scope. */
- GCC_METHOD0 (gcc_decl, get_current_binding_level_decl)
- /* Make the current binding level an inline namespace. It must be a
- namespace to begin with. It is safe to call this more than once
- for the same namespace, but after the first call, subsequent ones
- will not return a success status. */
- GCC_METHOD0 (int /* bool */, make_namespace_inline)
- /* Add USED_NS to the namespaces used by the current binding level.
- Use get_current_binding_level_decl to obtain USED_NS's
- gcc_decl. */
- GCC_METHOD1 (int /* bool */, add_using_namespace,
- gcc_decl) /* Argument USED_NS. */
- /* Introduce a namespace alias declaration, as in:
- namespace foo = [... ::] bar;
- After this call, namespace TARGET will be visible as ALIAS within
- the current namespace. Get the declaration for TARGET by calling
- get_current_binding_level_decl after pushing into it. */
- GCC_METHOD2 (int /* bool */, add_namespace_alias,
- const char *, /* Argument ALIAS. */
- gcc_decl) /* Argument TARGET. */
- /* Introduce a using declaration, as in:
- using foo::bar;
- The TARGET decl names the qualifying scope (foo:: above) and the
- identifier (bar), but that does not mean that only TARGET will be
- brought into the current scope: all bindings of TARGET's identifier
- in the qualifying scope will be brought in.
- FLAGS should specify GCC_CP_SYMBOL_USING. If the current scope is
- a class scope, visibility flags must be supplied.
- Even when TARGET is template dependent, we don't need to specify
- whether or not it is a typename: the supplied declaration (that
- could be a template-dependent type converted to declaration by
- get_type_decl) indicates so. */
- GCC_METHOD2 (int /* bool */, add_using_decl,
- enum gcc_cp_symbol_kind, /* Argument FLAGS. */
- gcc_decl) /* Argument TARGET. */
- /* Create a new "decl" in GCC, and bind it in the current binding
- level. A decl is a declaration, basically a kind of symbol.
- NAME is the name of the new symbol. SYM_KIND is the kind of
- symbol being requested. SYM_TYPE is the new symbol's C++ type;
- except for labels, where this is not meaningful and should be
- zero. If SUBSTITUTION_NAME is not NULL, then a reference to this
- decl in the source will later be substituted with a dereference
- of a variable of the given name. Otherwise, for symbols having
- an address (e.g., functions), ADDRESS is the address. FILENAME
- and LINE_NUMBER refer to the symbol's source location. If this
- is not known, FILENAME can be NULL and LINE_NUMBER can be 0.
- This function returns the new decl.
- Use this function to register typedefs, functions and variables to
- namespace and local binding levels, and typedefs, member functions
- (static or not), and static data members to class binding levels.
- Class members must have their access controls specified with
- GCC_CP_ACCESS_* flags in SYM_KIND.
- Note that, since access controls are disabled, we have no means to
- express private, protected and public.
- There are various flags that can be set in SYM_KIND to specify
- additional semantics. Look for GCC_CP_FLAGs in the definition of
- enum gcc_cp_symbol_kind in gcc-cp-interface.h.
- In order to define member functions, pass GCC_CP_SYMBOL_FUNCTION in
- SYM_KIND, and a function_type for static member functions or a
- method type for non-static member functions, including constructors
- and destructors. Use build_function_type to create a function
- type; for a method type, start by creating a function type without
- any compiler-introduced artificial arguments (the implicit this
- pointer, and the __in_chrg added to constructors and destructors,
- and __vtt_parm added to the former), and then use build_method_type
- to create the method type out of the class type and the function
- type.
- For operator functions, set GCC_CP_FLAG_SPECIAL_FUNCTION in
- SYM_KIND, in addition to any other applicable flags, and pass as
- NAME a string starting with the two-character mangling for operator
- name: "ps" for unary plus, "mL" for multiply and assign, *=; etc.
- Use "cv" for type converstion operators (the target type portion
- may be omitted, as it is taken from the return type in SYM_TYPE).
- For operator"", use "li" followed by the identifier (the mangled
- name mandates digits specifying the length of the identifier; if
- present, they determine the end of the identifier, otherwise, the
- identifier extents to the end of the string, so that "li3_Kme" and
- "li_Km" are equivalent).
- Constructors and destructors need special care, because for each
- constructor and destructor there may be multiple clones defined
- internally by the compiler. With build_decl, you can introduce the
- base declaration of a constructor or a destructor, setting
- GCC_CP_FLAG_SPECIAL_FUNCTION the flag and using names starting with
- capital "C" or "D", respectively, followed by a digit (see below),
- a blank, or NUL ('\0'). DO NOT supply an ADDRESS or a
- SUBSTITUTION_NAME to build_decl, it would be meaningless (and
- rejected) for the base declaration; use define_cdtor_clone to
- introduce the address of each clone. For constructor templates,
- declare the template with build_decl, and then, for each
- specialization, introduce it with
- build_function_template_specialization, and then define the
- addresses of each of its clones with define_cdtor_clone.
- NAMEs for GCC_CP_FLAG_SPECIAL_FUNCTION:
- NAME meaning
- C? constructor base declaration (? may be 1, 2, 4, blank or NUL)
- D? destructor base declaration (? may be 0, 1, 2, 4, blank or NUL)
- nw operator new
- na operator new[]
- dl operator delete
- da operator delete[]
- ps operator + (unary)
- ng operator - (unary)
- ad operator & (unary)
- de operator * (unary)
- co operator ~
- pl operator +
- mi operator -
- ml operator *
- dv operator /
- rm operator %
- an operator &
- or operator |
- eo operator ^
- aS operator =
- pL operator +=
- mI operator -=
- mL operator *=
- dV operator /=
- rM operator %=
- aN operator &=
- oR operator |=
- eO operator ^=
- ls operator <<
- rs operator >>
- lS operator <<=
- rS operator >>=
- eq operator ==
- ne operator !=
- lt operator <
- gt operator >
- le operator <=
- ge operator >=
- nt operator !
- aa operator &&
- oo operator ||
- pp operator ++
- mm operator --
- cm operator ,
- pm operator ->*
- pt operator ->
- cl operator ()
- ix operator []
- qu operator ?
- cv operator <T> (conversion operator)
- li<id> operator "" <id>
- FIXME: How about attributes? */
- GCC_METHOD7 (gcc_decl, build_decl,
- const char *, /* Argument NAME. */
- enum gcc_cp_symbol_kind, /* Argument SYM_KIND. */
- gcc_type, /* Argument SYM_TYPE. */
- const char *, /* Argument SUBSTITUTION_NAME. */
- gcc_address, /* Argument ADDRESS. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Supply the ADDRESS of one of the multiple clones of constructor or
- destructor CDTOR. The clone is specified by NAME, using the
- following name mangling conventions:
- C1 in-charge constructor
- C2 not-in-charge constructor
- C4 unified constructor
- D0 deleting destructor
- D1 in-charge destructor
- D2 not-in-charge destructor
- D4 unified destructor
- The following information is not necessary to use the API.
- C1 initializes an instance of the class (rather than of derived
- classes), including virtual base classes, whereas C2 initializes a
- sub-object (of the given class type) of an instance of some derived
- class (or a full object that doesn't have any virtual base
- classes).
- D0 and D1 destruct an instance of the class, including virtual base
- classes, but only the former calls operator delete to release the
- object's storage at the end; D2 destructs a sub-object (of the
- given class type) of an instance of a derived class (or a full
- object that doesn't have any virtual base classes).
- The [CD]4 manglings (and symbol definitions) are non-standard, but
- GCC uses them in some cases: rather than assuming they are
- in-charge or not-in-charge, they test the implicit argument that
- the others ignore to tell how to behave. These are used instead of
- cloning when we just can't use aliases. */
- GCC_METHOD3 (gcc_decl, define_cdtor_clone,
- const char *, /* Argument NAME. */
- gcc_decl, /* Argument CDTOR. */
- gcc_address) /* Argument ADDRESS. */
- /* Return the type associated with the given declaration. This is
- most useful to obtain the type associated with a forward-declared
- class, because it is the gcc_type, rather than the gcc_decl, that
- has to be used to build other types, but build_decl returns a
- gcc_decl rather than a gcc_type. This call can in theory be used
- to obtain the type from any other declaration; it is supposed to
- return the same type that was supplied when the declaration was
- created. */
- GCC_METHOD1 (gcc_type, get_decl_type,
- gcc_decl) /* Argument DECL. */
- /* Return the declaration for a type. */
- GCC_METHOD1 (gcc_decl, get_type_decl,
- gcc_type) /* Argument TYPE. */
- /* Declare DECL as a friend of the current class scope, if TYPE is
- NULL, or of TYPE itself otherwise. DECL may be a function or a
- class, be they template generics, template specializations or not
- templates. TYPE must be a class type (not a template generic).
- The add_friend call cannot introduce a declaration; even if the
- friend is first declared as a friend in the source code, the
- declaration belongs in the enclosing namespace, so it must be
- introduced in that namespace, and the resulting declaration can
- then be made a friend.
- DECL cannot, however, be a member of a template class generic,
- because we have no means to introduce their declarations. This
- interface has no notion of definitions for template generics. As a
- consequence, users of this interface must introduce each friend
- template member specialization separately, i.e., instead of:
- template <typename T> friend struct X<T>::M;
- they must be declared as if they were:
- friend struct X<onetype>::M;
- friend struct X<anothertype>::M;
- ... for each specialization of X.
- Specializations of a template can have each others' members as
- friends:
- template <typename T> class foo {
- int f();
- template <typename U> friend int foo<U>::f();
- };
- It wouldn't always be possible to define all specializations of a
- template class before introducing the friend declarations in their
- expanded, per-specialization form.
- In order to simplify such friend declarations, and to enable
- incremental friend declarations as template specializations are
- introduced, add_friend can be called after the befriending class is
- fully defined, passing it a non-NULL TYPE argument naming the
- befriending class type. */
- GCC_METHOD2 (int /* bool */, add_friend,
- gcc_decl, /* Argument DECL. */
- gcc_type) /* Argument TYPE. */
- /* Return the type of a pointer to a given base type. */
- GCC_METHOD1 (gcc_type, build_pointer_type,
- gcc_type) /* Argument BASE_TYPE. */
- /* Return the type of a reference to a given base type. */
- GCC_METHOD2 (gcc_type, build_reference_type,
- gcc_type, /* Argument BASE_TYPE. */
- enum gcc_cp_ref_qualifiers) /* Argument RQUALS. */
- /* Create a new pointer-to-member type. MEMBER_TYPE is the data
- member type, while CLASS_TYPE is the class type containing the data
- member. For pointers to member functions, MEMBER_TYPE must be a
- method type, and CLASS_TYPE must be specified even though it might
- be possible to extract it from the method type. */
- GCC_METHOD2 (gcc_type, build_pointer_to_member_type,
- gcc_type, /* Argument CLASS_TYPE. */
- gcc_type) /* Argument MEMBER_TYPE. */
- /* Start a template parameter list scope and enters it, so that
- subsequent build_type_template_parameter and
- build_value_template_parameter calls create template parameters in
- the list. The list is closed by a build_decl call with
- GCC_CP_SYMBOL_FUNCTION or GCC_CP_SYMBOL_CLASS, that, when the scope
- is a template parameter list, declares a template function or a
- template class with the then-closed parameter list. The scope in
- which the new declaration is to be introduced by build_decl must be
- entered before calling start_template_decl, and build_decl returns
- to that scope, from the template parameter list scope, before
- introducing the declaration. */
- GCC_METHOD0 (int /* bool */, start_template_decl)
- /* Build a typename template-parameter (e.g., the T in template
- <typename T = X>). Either PACK_P should be nonzero, to indicate an
- argument pack (the last argument in a variadic template argument
- list, as in template <typename... T>), or DEFAULT_TYPE may be
- non-NULL to set the default type argument (e.g. X) for the template
- parameter. FILENAME and LINE_NUMBER may specify the source
- location in which the template parameter was declared. */
- GCC_METHOD5 (gcc_type, build_type_template_parameter,
- const char *, /* Argument ID. */
- int /* bool */, /* Argument PACK_P. */
- gcc_type, /* Argument DEFAULT_TYPE. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Build a template template-parameter (e.g., the T in template
- <template <[...]> class T = X>). DEFAULT_TEMPL may be non-NULL to
- set the default type-template argument (e.g. X) for the template
- template parameter. FILENAME and LINE_NUMBER may specify the
- source location in which the template parameter was declared. */
- GCC_METHOD5 (gcc_utempl, build_template_template_parameter,
- const char *, /* Argument ID. */
- int /* bool */, /* Argument PACK_P. */
- gcc_utempl, /* Argument DEFAULT_TEMPL. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Build a value template-parameter (e.g., the V in template <typename
- T, T V> or in template <int V = X>). DEFAULT_VALUE may be non-NULL
- to set the default value argument for the template parameter (e.g.,
- X). FILENAME and LINE_NUMBER may specify the source location in
- which the template parameter was declared. */
- GCC_METHOD5 (gcc_decl, build_value_template_parameter,
- gcc_type, /* Argument TYPE. */
- const char *, /* Argument ID. */
- gcc_expr, /* Argument DEFAULT_VALUE. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Build a template-dependent typename (e.g., typename T::bar or
- typename T::template bart<X>). ENCLOSING_TYPE should be the
- template-dependent nested name specifier (e.g., T), ID should be
- the name of the member of the ENCLOSING_TYPE (e.g., bar or bart),
- and TARGS should be non-NULL and specify the template arguments
- (e.g. <X>) iff ID is to name a class template.
- In this and other calls, a template-dependent nested name specifier
- may be a template class parameter (build_type_template_parameter),
- a specialization (returned by build_dependent_type_template_id) of
- a template template parameter (returned by
- build_template_template_parameter) or a member type thereof
- (returned by build_dependent_typename itself). */
- GCC_METHOD3 (gcc_type, build_dependent_typename,
- gcc_type, /* Argument ENCLOSING_TYPE. */
- const char *, /* Argument ID. */
- const struct gcc_cp_template_args *) /* Argument TARGS. */
- /* Build a template-dependent class template (e.g., T::template bart).
- ENCLOSING_TYPE should be the template-dependent nested name
- specifier (e.g., T), ID should be the name of the class template
- member of the ENCLOSING_TYPE (e.g., bart). */
- GCC_METHOD2 (gcc_utempl, build_dependent_class_template,
- gcc_type, /* Argument ENCLOSING_TYPE. */
- const char *) /* Argument ID. */
- /* Build a template-dependent type template-id (e.g., T<A>).
- TEMPLATE_DECL should be a template template parameter (e.g., the T
- in template <template <[...]> class T = X>), and TARGS should
- specify the template arguments (e.g. <A>). */
- GCC_METHOD2 (gcc_type, build_dependent_type_template_id,
- gcc_utempl, /* Argument TEMPLATE_DECL. */
- const struct gcc_cp_template_args *) /* Argument TARGS. */
- /* Build a template-dependent expression (e.g., S::val or S::template
- mtf<X>, or unqualified f or template tf<X>).
- ENCLOSING_SCOPE should be a template-dependent nested name
- specifier (e.g., T), a resolved namespace or class decl, or NULL
- for unqualified names; ID should be the name of the member of the
- ENCLOSING_SCOPE (e.g., val or mtf) or unqualified overloaded
- function; and TARGS should list template arguments (e.g. <X>) when
- mtf or tf are to name a template function, or be NULL otherwise.
- Unqualified names and namespace- or class-qualified names can only
- resolve to overloaded functions, to be used in contexts that
- involve overload resolution that cannot be resolved because of
- template-dependent argument or return types, such as call
- expressions with template-dependent arguments, conversion
- expressions to function types with template-dependent argument
- types or the like. Other cases of unqualified or
- non-template-dependent-qualified names should NOT use this
- function, and use decl_expr to convert the appropriate function or
- object declaration to an expression.
- If ID is the name of a special member function, FLAGS should be
- GCC_CP_SYMBOL_FUNCTION|GCC_CP_FLAG_SPECIAL_FUNCTION, and ID should
- be one of the encodings for special member functions documented in
- build_decl. Otherwise, FLAGS should be GCC_CP_SYMBOL_MASK, which
- suggests the symbol kind is not known (though we know it is not a
- type).
- If ID denotes a conversion operator, CONV_TYPE should name the
- target type of the conversion. Otherwise, CONV_TYPE must be
- NULL. */
- GCC_METHOD5 (gcc_expr, build_dependent_expr,
- gcc_decl, /* Argument ENCLOSING_SCOPE. */
- enum gcc_cp_symbol_kind, /* Argument FLAGS. */
- const char *, /* Argument NAME. */
- gcc_type, /* Argument CONV_TYPE. */
- const struct gcc_cp_template_args *) /* Argument TARGS. */
- /* Build a gcc_expr for the value VALUE in type TYPE. */
- GCC_METHOD2 (gcc_expr, build_literal_expr,
- gcc_type, /* Argument TYPE. */
- unsigned long) /* Argument VALUE. */
- /* Build a gcc_expr that denotes DECL, the declaration of a variable
- or function in namespace scope, or of a static member variable or
- function. Use QUALIFIED_P to build the operand of unary & so as to
- compute a pointer-to-member, rather than a regular pointer. */
- GCC_METHOD2 (gcc_expr, build_decl_expr,
- gcc_decl, /* Argument DECL. */
- int /* bool */) /* Argument QUALIFIED_P. */
- /* Build a gcc_expr that denotes the unary operation UNARY_OP applied
- to the gcc_expr OPERAND. For non-expr operands, see
- unary_type_expr. Besides the UNARY_OP encodings used for operator
- names, we support "pp_" for preincrement, and "mm_" for
- predecrement, "nx" for noexcept, "tw" for throw, "tr" for rethrow
- (pass NULL as the operand), "te" for typeid, "sz" for sizeof, "az"
- for alignof, "dl" for delete, "gsdl" for ::delete, "da" for
- delete[], "gsda" for ::delete[], "sp" for pack expansion, "sZ" for
- sizeof...(function argument pack). */
- GCC_METHOD2 (gcc_expr, build_unary_expr,
- const char *, /* Argument UNARY_OP. */
- gcc_expr) /* Argument OPERAND. */
- /* Build a gcc_expr that denotes the binary operation BINARY_OP
- applied to gcc_exprs OPERAND1 and OPERAND2. Besides the BINARY_OP
- encodings used for operator names, we support "ds" for the operator
- token ".*" and "dt" for the operator token ".". When using
- operators that take a name as their second operand ("." and "->")
- use decl_expr to convert the gcc_decl of the member name to a
- gcc_expr, if the member name wasn't created with
- e.g. build_dependent_expr. */
- GCC_METHOD3 (gcc_expr, build_binary_expr,
- const char *, /* Argument BINARY_OP. */
- gcc_expr, /* Argument OPERAND1. */
- gcc_expr) /* Argument OPERAND2. */
- /* Build a gcc_expr that denotes the ternary operation TERNARY_OP
- applied to gcc_exprs OPERAND1, OPERAND2 and OPERAND3. The only
- supported TERNARY_OP is "qu", for the "?:" operator. */
- GCC_METHOD4 (gcc_expr, build_ternary_expr,
- const char *, /* Argument TERNARY_OP. */
- gcc_expr, /* Argument OPERAND1. */
- gcc_expr, /* Argument OPERAND2. */
- gcc_expr) /* Argument OPERAND3. */
- /* Build a gcc_expr that denotes the unary operation UNARY_OP applied
- to the gcc_type OPERAND. Supported unary operations taking types
- are "ti" for typeid, "st" for sizeof, "at" for alignof, and "sZ"
- for sizeof...(template argument pack). */
- GCC_METHOD2 (gcc_expr, build_unary_type_expr,
- const char *, /* Argument UNARY_OP. */
- gcc_type) /* Argument OPERAND. */
- /* Build a gcc_expr that denotes the binary operation BINARY_OP
- applied to gcc_type OPERAND1 and gcc_expr OPERAND2. Use this for
- all kinds of (single-argument) type casts ("dc", "sc", "cc", "rc"
- for dynamic, static, const and reinterpret casts, respectively;
- "cv" for functional or C-style casts). */
- GCC_METHOD3 (gcc_expr, build_cast_expr,
- const char *, /* Argument BINARY_OP. */
- gcc_type, /* Argument OPERAND1. */
- gcc_expr) /* Argument OPERAND2. */
- /* Build a gcc_expr that denotes the conversion of an expression list
- VALUES to TYPE, with ("tl") or without ("cv") braces, or a braced
- initializer list of unspecified type (e.g., a component of another
- braced initializer list; pass "il" for CONV_OP, and NULL for
- TYPE). */
- GCC_METHOD3 (gcc_expr, build_expression_list_expr,
- const char *, /* Argument CONV_OP. */
- gcc_type, /* Argument TYPE. */
- const struct gcc_cp_function_args *) /* Argument VALUES. */
- /* Build a gcc_expr that denotes a new ("nw") or new[] ("na")
- expression of TYPE, with or without a GLOBAL_NS qualifier (prefix
- the NEW_OP with "gs"), with or without PLACEMENT, with or without
- INITIALIZER. If it's not a placement new, PLACEMENT must be NULL
- (rather than a zero-length placement arg list). If there's no
- specified initializer, INITIALIZER must be NULL; a zero-length arg
- list stands for a default initializer. */
- GCC_METHOD4 (gcc_expr, build_new_expr,
- const char *, /* Argument NEW_OP. */
- const struct gcc_cp_function_args *, /* Argument PLACEMENT. */
- gcc_type, /* Argument TYPE. */
- const struct gcc_cp_function_args *) /* Argument INITIALIZER. */
- /* Return a call expression that calls CALLABLE with arguments ARGS.
- CALLABLE may be a function, a callable object, a pointer to
- function, an unresolved expression, an unresolved overload set, an
- object expression combined with a member function overload set or a
- pointer-to-member. If QUALIFIED_P, CALLABLE will be interpreted as
- a qualified name, preventing virtual function dispatch. */
- GCC_METHOD3 (gcc_expr, build_call_expr,
- gcc_expr, /* Argument CALLABLE. */
- int /* bool */, /* Argument QUALIFIED_P. */
- const struct gcc_cp_function_args *) /* Argument ARGS. */
- /* Return the type of the gcc_expr OPERAND.
- Use this for decltype.
- For decltype (auto), pass a NULL OPERAND.
- Note: for template-dependent expressions, the result is NULL,
- because the type is only computed when template argument
- substitution is performed. */
- GCC_METHOD1 (gcc_type, get_expr_type,
- gcc_expr) /* Argument OPERAND. */
- /* Introduce a specialization of a template function.
- TEMPLATE_DECL is the template function, and TARGS are the arguments
- for the specialization. ADDRESS is the address of the
- specialization. FILENAME and LINE_NUMBER specify the source
- location associated with the template function specialization. */
- GCC_METHOD5 (gcc_decl, build_function_template_specialization,
- gcc_decl, /* Argument TEMPLATE_DECL. */
- const struct gcc_cp_template_args *, /* Argument TARGS. */
- gcc_address, /* Argument ADDRESS. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Specialize a template class as an incomplete type. A definition
- can be supplied later, with start_class_type.
- TEMPLATE_DECL is the template class, and TARGS are the arguments
- for the specialization. FILENAME and LINE_NUMBER specify the
- source location associated with the template class
- specialization. */
- GCC_METHOD4 (gcc_decl, build_class_template_specialization,
- gcc_decl, /* Argument TEMPLATE_DECL. */
- const struct gcc_cp_template_args *, /* Argument TARGS. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Start defining a 'class', 'struct' or 'union' type, entering its
- own binding level. Initially it has no fields.
- TYPEDECL is the forward-declaration of the type, returned by
- build_decl. BASE_CLASSES indicate the base classes of class NAME.
- FILENAME and LINE_NUMBER specify the source location associated
- with the class definition, should they be different from those of
- the forward declaration. */
- GCC_METHOD4 (gcc_type, start_class_type,
- gcc_decl, /* Argument TYPEDECL. */
- const struct gcc_vbase_array *,/* Argument BASE_CLASSES. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Create a new closure class type, record it as the
- DISCRIMINATOR-numbered closure type in the current scope (or
- associated with EXTRA_SCOPE, if non-NULL), and enter the closure
- type's own binding level. This primitive would sort of combine
- build_decl and start_class_type, if they could be used to introduce
- a closure type. Initially it has no fields.
- FILENAME and LINE_NUMBER specify the source location associated
- with the class. EXTRA_SCOPE, if non-NULL, must be a PARM_DECL of
- the current function, or a FIELD_DECL of the current class. If it
- is NULL, the current scope must be a function. */
- GCC_METHOD5 (gcc_type, start_closure_class_type,
- int, /* Argument DISCRIMINATOR. */
- gcc_decl, /* Argument EXTRA_SCOPE. */
- enum gcc_cp_symbol_kind, /* Argument FLAGS. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Add a non-static data member to the most-recently-started
- unfinished struct or union type. FIELD_NAME is the field's name.
- FIELD_TYPE is the type of the field. BITSIZE and BITPOS indicate
- where in the struct the field occurs. */
- GCC_METHOD5 (gcc_decl, build_field,
- const char *, /* Argument FIELD_NAME. */
- gcc_type, /* Argument FIELD_TYPE. */
- enum gcc_cp_symbol_kind, /* Argument FIELD_FLAGS. */
- unsigned long, /* Argument BITSIZE. */
- unsigned long) /* Argument BITPOS. */
- /* After all the fields have been added to a struct, class or union,
- the struct or union type must be "finished". This does some final
- cleanups in GCC, and pops to the binding level that was in effect
- before the matching start_class_type or
- start_closure_class_type. */
- GCC_METHOD1 (int /* bool */, finish_class_type,
- unsigned long) /* Argument SIZE_IN_BYTES. */
- /* Create a new 'enum' type, and record it in the current binding
- level. The new type initially has no associated constants.
- NAME is the enum name. FILENAME and LINE_NUMBER specify its source
- location. */
- GCC_METHOD5 (gcc_type, start_enum_type,
- const char *, /* Argument NAME. */
- gcc_type, /* Argument UNDERLYING_INT_TYPE. */
- enum gcc_cp_symbol_kind, /* Argument FLAGS. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Add a new constant to an enum type. NAME is the constant's name
- and VALUE is its value. Returns a gcc_decl for the constant. */
- GCC_METHOD3 (gcc_decl, build_enum_constant,
- gcc_type, /* Argument ENUM_TYPE. */
- const char *, /* Argument NAME. */
- unsigned long) /* Argument VALUE. */
- /* After all the constants have been added to an enum, the type must
- be "finished". This does some final cleanups in GCC. */
- GCC_METHOD1 (int /* bool */, finish_enum_type,
- gcc_type) /* Argument ENUM_TYPE. */
- /* Create a new function type. RETURN_TYPE is the type returned by
- the function, and ARGUMENT_TYPES is a vector, of length NARGS, of
- the argument types. IS_VARARGS is true if the function is
- varargs. */
- GCC_METHOD3 (gcc_type, build_function_type,
- gcc_type, /* Argument RETURN_TYPE. */
- const struct gcc_type_array *,/* Argument ARGUMENT_TYPES. */
- int /* bool */) /* Argument IS_VARARGS. */
- /* Create a variant of a function type with an exception
- specification. FUNCTION_TYPE is a function or method type.
- EXCEPT_TYPES is an array with the list of exception types. Zero as
- the array length implies throw() AKA noexcept(true); NULL as the
- pointer to gcc_type_array implies noexcept(false), which is almost
- equivalent (but distinguishable by the compiler) to an unspecified
- exception list. */
- GCC_METHOD2 (gcc_type, build_exception_spec_variant,
- gcc_type, /* Argument FUNCTION_TYPE. */
- const struct gcc_type_array *)/* Argument EXCEPT_TYPES. */
- /* Create a new non-static member function type. FUNC_TYPE is the
- method prototype, without the implicit THIS pointer, added as a
- pointer to the QUALS-qualified CLASS_TYPE. If CLASS_TYPE is NULL,
- this creates a cv-qualified (member) function type not associated
- with any specific class, as needed to support "typedef void f(int)
- const;", which can later be used to declare member functions and
- pointers to member functions. */
- GCC_METHOD4 (gcc_type, build_method_type,
- gcc_type, /* Argument CLASS_TYPE. */
- gcc_type, /* Argument FUNC_TYPE. */
- enum gcc_cp_qualifiers, /* Argument QUALS. */
- enum gcc_cp_ref_qualifiers) /* Argument RQUALS. */
- /* Return a declaration for the (INDEX - 1)th argument of
- FUNCTION_DECL, i.e., for the first argument, use zero as the index.
- If FUNCTION_DECL is a non-static member function, use -1 to get the
- implicit THIS parameter. */
- GCC_METHOD2 (gcc_decl, get_function_parameter_decl,
- gcc_decl, /* Argument FUNCTION_DECL. */
- int) /* Argument INDEX. */
- /* Return a lambda expr that constructs an instance of CLOSURE_TYPE.
- Only lambda exprs without any captures can be correctly created
- through these mechanisms; that's all we need to support lambdas
- expressions in default parameters, the only kind that may have to
- be introduced through this interface. */
- GCC_METHOD1 (gcc_expr, build_lambda_expr,
- gcc_type) /* Argument CLOSURE_TYPE. */
- /* Return an integer type with the given properties. If BUILTIN_NAME
- is non-NULL, it must name a builtin integral type with the given
- signedness and size, and that is the type that will be returned. */
- GCC_METHOD3 (gcc_type, get_int_type,
- int /* bool */, /* Argument IS_UNSIGNED. */
- unsigned long, /* Argument SIZE_IN_BYTES. */
- const char *) /* Argument BUILTIN_NAME. */
- /* Return the 'char' type, a distinct type from both 'signed char' and
- 'unsigned char' returned by int_type. */
- GCC_METHOD0 (gcc_type, get_char_type)
- /* Return a floating point type with the given properties. If BUILTIN_NAME
- is non-NULL, it must name a builtin integral type with the given
- signedness and size, and that is the type that will be returned. */
- GCC_METHOD2 (gcc_type, get_float_type,
- unsigned long, /* Argument SIZE_IN_BYTES. */
- const char *) /* Argument BUILTIN_NAME. */
- /* Return the 'void' type. */
- GCC_METHOD0 (gcc_type, get_void_type)
- /* Return the 'bool' type. */
- GCC_METHOD0 (gcc_type, get_bool_type)
- /* Return the std::nullptr_t type. */
- GCC_METHOD0 (gcc_type, get_nullptr_type)
- /* Return the nullptr constant. */
- GCC_METHOD0 (gcc_expr, get_nullptr_constant)
- /* Create a new array type. If NUM_ELEMENTS is -1, then the array
- is assumed to have an unknown length. */
- GCC_METHOD2 (gcc_type, build_array_type,
- gcc_type, /* Argument ELEMENT_TYPE. */
- int) /* Argument NUM_ELEMENTS. */
- /* Create a new array type. NUM_ELEMENTS is a template-dependent
- expression. */
- GCC_METHOD2 (gcc_type, build_dependent_array_type,
- gcc_type, /* Argument ELEMENT_TYPE. */
- gcc_expr) /* Argument NUM_ELEMENTS. */
- /* Create a new variably-sized array type. UPPER_BOUND_NAME is the
- name of a local variable that holds the upper bound of the array;
- it is one less than the array size. */
- GCC_METHOD2 (gcc_type, build_vla_array_type,
- gcc_type, /* Argument ELEMENT_TYPE. */
- const char *) /* Argument UPPER_BOUND_NAME. */
- /* Return a qualified variant of a given base type. QUALIFIERS says
- which qualifiers to use; it is composed of or'd together
- constants from 'enum gcc_cp_qualifiers'. */
- GCC_METHOD2 (gcc_type, build_qualified_type,
- gcc_type, /* Argument UNQUALIFIED_TYPE. */
- enum gcc_cp_qualifiers) /* Argument QUALIFIERS. */
- /* Build a complex type given its element type. */
- GCC_METHOD1 (gcc_type, build_complex_type,
- gcc_type) /* Argument ELEMENT_TYPE. */
- /* Build a vector type given its element type and number of
- elements. */
- GCC_METHOD2 (gcc_type, build_vector_type,
- gcc_type, /* Argument ELEMENT_TYPE. */
- int) /* Argument NUM_ELEMENTS. */
- /* Build a constant. NAME is the constant's name and VALUE is its
- value. FILENAME and LINE_NUMBER refer to the type's source
- location. If this is not known, FILENAME can be NULL and
- LINE_NUMBER can be 0. */
- GCC_METHOD5 (int /* bool */, build_constant,
- gcc_type, /* Argument TYPE. */
- const char *, /* Argument NAME. */
- unsigned long, /* Argument VALUE. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- /* Emit an error and return an error type object. */
- GCC_METHOD1 (gcc_type, error,
- const char *) /* Argument MESSAGE. */
- /* Declare a static_assert with the given CONDITION and ERRORMSG at
- FILENAME:LINE_NUMBER. */
- GCC_METHOD4 (int /* bool */, add_static_assert,
- gcc_expr, /* Argument CONDITION. */
- const char *, /* Argument ERRORMSG. */
- const char *, /* Argument FILENAME. */
- unsigned int) /* Argument LINE_NUMBER. */
- #if 0
- /* FIXME: We don't want to expose the internal implementation detail
- that default parms are stored in function types, and it's not clear
- how this or other approaches would interact with the type sharing
- of e.g. ctor clones, so we're leaving this out, since default args
- are not even present in debug information anyway. Besides, the set
- of default args for a function may grow within its scope, and vary
- independently in other scopes. */
- /* Create a modified version of a function type that has default
- values for some of its arguments. The returned type should ONLY be
- used to define functions or methods, never to declare parameters,
- variables, types or the like.
- DEFAULTS must have at most as many N_ELEMENTS as there are
- arguments without default values in FUNCTION_TYPE. Say, if
- FUNCTION_TYPE has an argument list such as (T1, T2, T3, T4 = V0)
- and DEFAULTS has 2 elements (V1, V2), the returned type will have
- the following argument list: (T1, T2 = V1, T3 = V2, T4 = V0).
- Any NULL expressions in DEFAULTS will be marked as deferred, and
- they should be filled in with set_deferred_function_default_args. */
- GCC_METHOD2 (gcc_type, add_function_default_args,
- gcc_type, /* Argument FUNCTION_TYPE. */
- const struct gcc_cp_function_args *) /* Argument DEFAULTS. */
- /* Fill in the first deferred default args in FUNCTION_DECL with the
- expressions given in DEFAULTS. This can be used when the
- declaration of a parameter is needed to create a default
- expression, such as taking the size of an earlier parameter, or
- building a lambda expression in the parameter's context. */
- GCC_METHOD2 (int /* bool */, set_deferred_function_default_args,
- gcc_decl, /* Argument FUNCTION_DECL. */
- const struct gcc_cp_function_args *) /* Argument DEFAULTS. */
- #endif
- /* When you add entry points, add them at the end, so that the new API
- version remains compatible with the old version.
- The following conventions have been observed as to naming entry points:
- - build_* creates (and maybe records) something and returns it;
- - add_* creates and records something, but doesn't return it;
- - get_* obtains something without creating it;
- - start_* marks the beginning of a compound (type, list, ...);
- - finish_* completes the compound when needed.
- Entry points that return an int (bool) and don't have a return value
- specification return nonzero (true) on success and zero (false) on
- failure. This is in line with libcc1's conventions of returning a
- zero-initialized value in case of e.g. a transport error. */
|