(libc.info.gz) Extra Fast Growing

Info Catalog (libc.info.gz) Growing Objects (libc.info.gz) Obstacks (libc.info.gz) Status of an Obstack
 
 3.2.4.7 Extra Fast Growing Objects
 ..................................
 
 The usual functions for growing objects incur overhead for checking
 whether there is room for the new growth in the current chunk.  If you
 are frequently constructing objects in small steps of growth, this
 overhead can be significant.
 
    You can reduce the overhead by using special "fast growth" functions
 that grow the object without checking.  In order to have a robust
 program, you must do the checking yourself.  If you do this checking in
 the simplest way each time you are about to add data to the object, you
 have not saved anything, because that is what the ordinary growth
 functions do.  But if you can arrange to check less often, or check more
 efficiently, then you make the program faster.
 
    The function 'obstack_room' returns the amount of room available in
 the current chunk.  It is declared as follows:
 
  -- Function: int obstack_room (struct obstack *OBSTACK-PTR)
      Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | 
      POSIX Safety Concepts.
 
      This returns the number of bytes that can be added safely to the
      current growing object (or to an object about to be started) in
      obstack OBSTACK using the fast growth functions.
 
    While you know there is room, you can use these fast growth functions
 for adding data to a growing object:
 
  -- Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char
           C)
      Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
      corrupt mem |  POSIX Safety Concepts.
 
      The function 'obstack_1grow_fast' adds one byte containing the
      character C to the growing object in obstack OBSTACK-PTR.
 
  -- Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR,
           void *DATA)
      Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | 
      POSIX Safety Concepts.
 
      The function 'obstack_ptr_grow_fast' adds 'sizeof (void *)' bytes
      containing the value of DATA to the growing object in obstack
      OBSTACK-PTR.
 
  -- Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR,
           int DATA)
      Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | 
      POSIX Safety Concepts.
 
      The function 'obstack_int_grow_fast' adds 'sizeof (int)' bytes
      containing the value of DATA to the growing object in obstack
      OBSTACK-PTR.
 
  -- Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int
           SIZE)
      Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | 
      POSIX Safety Concepts.
 
      The function 'obstack_blank_fast' adds SIZE bytes to the growing
      object in obstack OBSTACK-PTR without initializing them.
 
    When you check for space using 'obstack_room' and there is not enough
 room for what you want to add, the fast growth functions are not safe.
 In this case, simply use the corresponding ordinary growth function
 instead.  Very soon this will copy the object to a new chunk; then there
 will be lots of room available again.
 
    So, each time you use an ordinary growth function, check afterward
 for sufficient space using 'obstack_room'.  Once the object is copied to
 a new chunk, there will be plenty of space again, so the program will
 start using the fast growth functions again.
 
    Here is an example:
 
      void
      add_string (struct obstack *obstack, const char *ptr, int len)
      {
        while (len > 0)
          {
            int room = obstack_room (obstack);
            if (room == 0)
              {
                /* Not enough room.  Add one character slowly,
                   which may copy to a new chunk and make room.  */
                obstack_1grow (obstack, *ptr++);
                len--;
              }
            else
              {
                if (room > len)
                  room = len;
                /* Add fast as much as we have room for. */
                len -= room;
                while (room-- > 0)
                  obstack_1grow_fast (obstack, *ptr++);
              }
          }
      }
 
Info Catalog (libc.info.gz) Growing Objects (libc.info.gz) Obstacks (libc.info.gz) Status of an Obstack
automatically generated by info2html