GCC Middle and Back End API Reference
vec.h File Reference

Go to the source code of this file.

Data Structures

struct  vec_prefix
struct  vl_embed
struct  vl_ptr
struct  va_heap
struct  va_gc
struct  va_gc_atomic
struct  vec< T, A, L >
struct  vnull
struct  vec< T, A, vl_embed >
struct  vec< T, va_heap, vl_ptr >
class  stack_vec< T, N >


void ggc_free (void *)
size_t ggc_round_alloc_size (size_t requested_size)
void * ggc_realloc_stat (void *, size_t MEM_STAT_DECL)
void dump_vec_loc_statistics (void)
template<typename T , typename A >
bool vec_safe_space ()
template<typename T , typename A >
unsigned vec_safe_length ()
template<typename T , typename A >
Tvec_safe_address ()
template<typename T , typename A >
bool vec_safe_is_empty ()
template<typename T , typename A >
bool vec_safe_reserve (vec< T, A, vl_embed > *&v, unsigned nelems, bool exact=false CXX_MEM_STAT_INFO)
template<typename T , typename A >
bool vec_safe_reserve_exact (vec< T, A, vl_embed > *&v, unsigned nelems CXX_MEM_STAT_INFO)
template<typename T , typename A >
void vec_alloc ()
template<typename T , typename A >
void vec_free ()
template<typename T , typename A >
void vec_safe_grow ()
template<typename T , typename A >
void vec_safe_grow_cleared ()
template<typename T , typename A >
bool vec_safe_iterate ()
template<typename T , typename A >
Tvec_safe_push ()
template<typename T , typename A >
void vec_safe_insert (vec< T, A, vl_embed > *&v, unsigned ix, const T &obj CXX_MEM_STAT_INFO)
template<typename T , typename A >
void vec_safe_truncate ()
template<typename T , typename A >
vec< T, A, vl_embed > * vec_safe_copy ()
template<typename T , typename A >
void vec_safe_splice (vec< T, A, vl_embed > *&dst, vec< T, A, vl_embed > *src CXX_MEM_STAT_INFO)
template<typename T >
void gt_ggc_mx ()
template<typename T , typename A >
void gt_pch_nx ()
template<typename T >
void vec_alloc ()
template<typename T >
void vec_check_alloc ()
template<typename T >
void vec_free ()


vnull vNULL

Function Documentation

void dump_vec_loc_statistics ( void  )

Templated vector type and associated interfaces.

The interface functions are typesafe and use inline functions, sometimes backed by out-of-line generic functions. The vectors are designed to interoperate with the GTY machinery.

There are both 'index' and 'iterate' accessors. The index accessor is implemented by operator[]. The iterator returns a boolean iteration condition and updates the iteration variable passed by reference. Because the iterator will be inlined, the address-of can be optimized away.

Each operation that increases the number of active elements is available in 'quick' and 'safe' variants. The former presumes that there is sufficient allocated space for the operation to succeed (it dies if there is not). The latter will reallocate the vector, if needed. Reallocation causes an exponential increase in vector size. If you know you will be adding N elements, it would be more efficient to use the reserve operation before adding the elements with the 'quick' operation. This will ensure there are at least as many elements as you ask for, it will exponentially increase if there are too few spare slots. If you want reserve a specific number of slots, but do not want the exponential increase (for instance, you know this is the last allocation), use the reserve_exact operation. You can also create a vector of a specific size from the get go.

You should prefer the push and pop operations, as they append and remove from the end of the vector. If you need to remove several items in one go, use the truncate operation. The insert and remove operations allow you to change elements in the middle of the vector. There are two remove operations, one which preserves the element ordering 'ordered_remove', and one which does not 'unordered_remove'. The latter function copies the end element into the removed slot, rather than invoke a memmove operation. The 'lower_bound' function will determine where to place an item in the array using insert that will maintain sorted order.

Vectors are template types with three arguments: the type of the elements in the vector, the allocation strategy, and the physical layout to use

Four allocation strategies are supported:

 - Heap: allocation is done using malloc/free.  This is the
   default allocation strategy.

 - GC: allocation is done using ggc_alloc/ggc_free.

 - GC atomic: same as GC with the exception that the elements
   themselves are assumed to be of an atomic type that does
   not need to be garbage collected.  This means that marking
   routines do not need to traverse the array marking the
   individual elements.  This increases the performance of
   GC activities.

Two physical layouts are supported:

 - Embedded: The vector is structured using the trailing array
   idiom.  The last member of the structure is an array of size
   1.  When the vector is initially allocated, a single memory
   block is created to hold the vector's control data and the
   array of elements.  These vectors cannot grow without
   reallocation (see discussion on embeddable vectors below).

 - Space efficient: The vector is structured as a pointer to an
   embedded vector.  This is the default layout.  It means that
   vectors occupy a single word of storage before initial
   allocation.  Vectors are allowed to grow (the internal
   pointer is reallocated but the main vector instance does not
   need to relocate).

The type, allocation and layout are specified when the vector is declared.

If you need to directly manipulate a vector, then the 'address' accessor will return the address of the start of the vector. Also the 'space' predicate will tell you whether there is spare capacity in the vector. You will not normally need to use these two functions.

Notes on the different layout strategies

  • Embeddable vectors (vec<T, A, vl_embed>)

    These vectors are suitable to be embedded in other data structures so that they can be pre-allocated in a contiguous memory block.

    Embeddable vectors are implemented using the trailing array idiom, thus they are not resizeable without changing the address of the vector object itself. This means you cannot have variables or fields of embeddable vector type -- always use a pointer to a vector. The one exception is the final field of a structure, which could be a vector type.

    You will have to use the embedded_size & embedded_init calls to create such objects, and they will not be resizeable (so the 'safe' allocation variants are not available).

    Properties of embeddable vectors:

     - The whole vector and control data are allocated in a single
       contiguous block.  It uses the trailing-vector idiom, so
       allocation must reserve enough space for all the elements
       in the vector plus its control data.
     - The vector cannot be re-allocated.
     - The vector cannot grow nor shrink.
     - No indirections needed for access/manipulation.
     - It requires 2 words of storage (prior to vector allocation).
  • Space efficient vector (vec<T, A, vl_ptr>)

    These vectors can grow dynamically and are allocated together with their control data. They are suited to be included in data structures. Prior to initial allocation, they only take a single word of storage.

    These vectors are implemented as a pointer to embeddable vectors. The semantics allow for this pointer to be NULL to represent empty vectors. This way, empty vectors occupy minimal space in the structure containing them.


    • The whole vector and control data are allocated in a single contiguous block.
    • The whole vector may be re-allocated.
    • Vector data may grow and shrink.
    • Access and manipulation requires a pointer test and indirection.
    • It requires 1 word of storage (prior to vector allocation).

An example of their use would be,

struct my_struct { // A space-efficient vector of tree pointers in GC memory. vec<tree, va_gc, vl_ptr> v; };

struct my_struct *s;

if (s->v.length ()) { we have some contents } s->v.safe_push (decl); // append some decl onto the end for (ix = 0; s->v.iterate (ix, &elt); ix++) { do something with elt }

   Support function for statistics.  
   Dump per-site memory statistics.  
void ggc_free ( void *  )
     Even if we think that GC is not enabled, the test that sets it is
     weak.  There are files compiled with -DGENERATOR_FILE that already
     include ggc.h.  We only need to provide these definitions if ggc.h
     has not been included.  Sigh.  
void* ggc_realloc_stat ( void *  ,
size_t  MEM_STAT_DECL 
size_t ggc_round_alloc_size ( size_t  requested_size)
template<typename T >
void gt_ggc_mx ( )
   Garbage collection support for vec<T, A, vl_embed>.  
     Nothing to do.  Vectors of atomic types wrt GC do not need to
     be traversed.  

References is_empty().

template<typename T , typename A >
void gt_pch_nx ( )
   PCH support for vec<T, A, vl_embed>.  
template<typename T , typename A >
void vec_alloc ( )
   Allocate GC memory for V with space for NELEMS slots.  If NELEMS
   is 0, V is initialized to NULL.  

References vec< T, A, vl_embed >::iterate().

Referenced by alloc_loop(), build_vector_from_val(), collect_one_action_chain(), vec< T, va_heap, vl_ptr >::space(), and workshare_safe_to_combine_p().

template<typename T >
void vec_alloc ( )
   Allocate heap memory for pointer V and create the internal vector
   with space for NELEMS elements.  If NELEMS is 0, the internal
   vector is initialized to empty.  
template<typename T >
void vec_check_alloc ( )
   Conditionally allocate heap memory for VEC and its internal vector.  

Referenced by target_handle_option().

template<typename T , typename A >
void vec_free ( )
   Free the GC memory allocated by vector V and set it to NULL.  

Referenced by strlen_dom_walker::before_dom_children(), memory_must_be_modified_in_insn_p(), and ssa_prop_init().

template<typename T >
void vec_free ( )
   Free the heap memory allocated by vector V and set it to NULL.  

References vec< T, va_heap, vl_ptr >::m_vec, and vNULL.

template<typename T , typename A >
T* vec_safe_address ( )
   If V is NULL, return NULL.  Otherwise, return V->address().  

Referenced by ipa_record_reference().

template<typename T , typename A >
vec<T, A, vl_embed>* vec_safe_copy ( )
   If SRC is not NULL, return a pointer to a copy of it.  

Referenced by create_trace_edges(), and inline_node_removal_hook().

template<typename T , typename A >
void vec_safe_grow ( )
   Grow V to length LEN.  Allocate it, if necessary.  

Referenced by ipa_record_reference().

template<typename T , typename A >
void vec_safe_grow_cleared ( )
   If V is NULL, allocate it.  Call V->safe_grow_cleared(LEN).  

References vec< T, A, vl_embed >::quick_push(), and vec_safe_reserve().

Referenced by add_cfi(), gimple_call_arg_flags(), input_eh_regions(), and replace_ssa_name().

template<typename T , typename A >
void vec_safe_insert ( vec< T, A, vl_embed > *&  v,
unsigned  ix,
const T &obj  CXX_MEM_STAT_INFO 
   if V has no room for one more element, reallocate it.  Then call
   V->quick_insert(IX, OBJ).  
template<typename T , typename A >
bool vec_safe_is_empty ( )
   If V is NULL, return true.  Otherwise, return V->is_empty().  

Referenced by dwarf2out_imported_module_or_decl_1(), and initializer_constant_valid_p_1().

template<typename T , typename A >
bool vec_safe_iterate ( )
template<typename T , typename A >
T* vec_safe_push ( )
   If V has no room for one more element, reallocate it.  Then call

References vec< T, A, vl_embed >::splice(), vec_safe_length(), and vec_safe_reserve_exact().

Referenced by add_forwarder_blocks(), add_ttypes_entry(), build3_stat(), ipa_modify_call_arguments(), move_stmt_eh_region_tree_nr(), and release_ssa_name().

template<typename T , typename A >
bool vec_safe_reserve ( vec< T, A, vl_embed > *&  v,
unsigned  nelems,
bool  exact = false CXX_MEM_STAT_INFO 
   If V does not have space for NELEMS elements, call
   V->reserve(NELEMS, EXACT).  

Referenced by vec_safe_grow_cleared(), and vec_safe_iterate().

template<typename T , typename A >
bool vec_safe_reserve_exact ( vec< T, A, vl_embed > *&  v,
unsigned nelems  CXX_MEM_STAT_INFO 

Referenced by vec_safe_push().

template<typename T , typename A >
bool vec_safe_space ( )
   Convenience wrapper functions to use when dealing with pointers to
   embedded vectors.  Some functionality for these vectors must be
   provided via free functions for these reasons:

        1- The pointer may be NULL (e.g., before initial allocation).

        2- When the vector needs to grow, it must be reallocated, so
           the pointer will change its value.

   Because of limitations with the current GC machinery, all vectors
   in GC memory *must* be pointers.  
   If V contains no room for NELEMS elements, return false. Otherwise,
   return true.  

References va_heap::reserve().

template<typename T , typename A >
void vec_safe_splice ( vec< T, A, vl_embed > *&  dst,
vec< T, A, vl_embed > *src  CXX_MEM_STAT_INFO 
   Copy the elements from SRC to the end of DST as if by memcpy.
   Reallocate DST, if necessary.  
template<typename T , typename A >
void vec_safe_truncate ( )
   If V is NULL, do nothing.  Otherwise, call V->truncate(SIZE).  

Referenced by clear_edges().

Variable Documentation

vnull vNULL

Vector API for GNU compiler. Copyright (C) 2004-2013 Free Software Foundation, Inc. Contributed by Nathan Sidwell natha.nosp@m.n@co.nosp@m.desou.nosp@m.rcer.nosp@m.y.com Re-implemented in C++ by Diego Novillo dnovi.nosp@m.llo@.nosp@m.googl.nosp@m.e.co.nosp@m.m

This file is part of GCC.

GCC 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, or (at your option) any later version.

GCC 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 GCC; see the file COPYING3. If not see http://www.gnu.org/licenses/.

   This file is compiled twice: once for the generator programs
   once for the compiler.  
   vNULL is an empty type with a template cast operation that returns
   a zero-initialized vec<T, A, L> instance.  Use this when you want
   to assign nil values to new vec instances or pass a nil vector as
   a function call argument.

   We use this technique because vec<T, A, L> must be PODs (they are
   stored in unions and passed in vararg functions), this means that
   they cannot have ctors/dtors.  

Referenced by add_subscript_strides(), analyze_scalar_evolution_for_address_of(), case_bit_test_cmp(), clone_inlined_nodes(), do_deref(), dump_split_point(), estimate_calls_size_and_time(), finish_cost_vectors(), finish_update_gimple_call(), free_dominance_info(), get_immediate_dominator(), get_initial_def_for_reduction(), graphite_can_represent_expr(), handle_lhs_call(), initiate_pass_states(), input_overwrite_node(), insert_aux(), ipa_tm_create_version(), is_included_in(), make_constraint_from(), make_constraints_to(), move_insn_for_shrink_wrap(), predicate_for_phi_result(), print_pred_bbs(), record_loop_exits(), safe_add(), scale_dominated_blocks_in_loop(), vec_free(), vect_create_vectorized_demotion_stmts(), vect_finish_stmt_generation(), vect_get_loop_based_defs(), vn_nary_op_insert_into(), and vn_reference_lookup_1().