#
# $Id: memqueue-extentsize.txt 308 2010-06-04 23:12:09Z nieves $
#
This note explains the background information, the isue and the solution
to the problem of reclaiming the unused space in memory-based queues, such
as used in the network server threads.

1. Background
-------------

This information is taken from the chapter

	Queue and Recno access method specific configuration
	Chapter 2.  Access Method Configuration 

in the Programer Reference. In particular, the sentence betwenn the **
is what applies to the issue here.

Selecting a Queue extent size -

In Queue databases, records are allocated sequentially and directly mapped
to an offset within the file storage for the database. As records are deleted
from the Queue, pages will become empty and will not be reused in normal
queue operations. To facilitate the reclamation of disk space a Queue may
be partitioned into extents. Each extent is kept in a separate physical file.

Extent files are automatically created as needed and marked for deletion
when the head of the queue moves off the extent. The extent will not be
deleted until all processes close the extent. In addition, Berkeley DB
caches a small number of extents that have been recently used;
this may delay when an extent will be deleted. The number of extents
left open depends on queue activity.

The extent size specifies the number of pages that make up each extent.
** By default, if no extent size is specified, the Queue resides in a
single file and disk space is not reclaimed. **
In choosing an extent size there is a
tradeoff between the amount of disk space used and the overhead of creating
and deleting files. If the extent size is too small, the system will pay a
performance penalty, creating and deleting files frequently.
In addition, if the active part of the queue spans many files,
all those files will need to be open at the same time, consuming system
and process file resources.
-

2. Issue
--------

The issue then is that for in-memory dbs, the function DB->set_q_extentsize
returns 0. We have this comment in pctldb.c:

  if(status == 0){
    /*
     * For a memory based queue (indicated by param->dbname set to NULL)
     * setting the extent size produces an error.
     */
    if((param->extent_size > 0) && (param->dbname != NULL))
      status = dbp->set_q_extentsize(dbp, param->extent_size);
  }

As a result, for in-memory dbs we need some other means of recovering that
space.

3. Solution
-----------

The solution is best exemplified by this other comment in lbqdb/dqb.c means
in the function qdb_rcv():

    /*
     * The call to truncate() below is added to handle the case of in-memory
     * queues, in which case the page/extent size mechanism for reclaiming
     * unused space does not operate (both calls return errors when the
     * data base is configured as in-memory db). If this is not done here,
     * or somewhere, then the cache is eventually exhasusted and the
     * the next calls to qdb_send return an error (memory cannot be allocated.)
     */
    if(nbspq->f_memory_based && (nbspq->n == 0))
      status = dbp->truncate(dbp, NULL, NULL, 0);
  }