\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setMotionQueueSize}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setMotionQueueSize}},
{\tt \manName{getMotionQueueSize}}
-- change the size of the RCCL motion queue.
}
\manSection{USAGE}
\cverbatim
setMotionQueueSize(mnp, size)
  MANIP *mnp;
  int size;

getMotionQueueSize(mnp)
  MANIP *mnp;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt size} --}
New size of the motion queue.
\manSection{RESTRICTIONS}
{\tt setMotionQueueSize()} must be called from the planning level.
\manSection{DESCRIPTION}
These routines
allow the size of a manipulator's motion queue to be
adjusted. Changing the motion queue size alters the maximum number of motions
that may be placed on the queue before calls to the {\it move}
primitives start to block. By playing with the motion queue size, different
blocking behaviours can be achieved.

If the motion queue size is set to 0, then all motion primitives will block
until the requested motion has completed. This is equivalent to calling
\cverbatim
        waitForCompleted(mnp); @endcverbatim
after every motion request.

If the motion queue size is set to 1, then all motion primitives will block
until the requested motion has started executing. This is a
blocking behaviour similar to that used by the language VAL-II.

If the motion queue size is $N$, then all motion 
primitives will block until there are less than $N$ items on the motion
queue.

{\tt setMotionQueueSize()} sets the size of the motion queue and
returns the previous size, if successful. {\tt getMotionQueueSize()} returns 
the current size of the motion queue.
The motion queue may be made as large as {\tt MAX_MQ_ENTRIES}. If the queue
is made smaller than the number of entries currently on it, then 
the next motion request will block until the required queue size
is satisfied.
\manSection{DIAGNOSTICS}
{\tt setMotionQueueSize()} returns {\tt -1} in the event of an error. 
It will automatically abort the program if the option {\tt RCCL_ERROR_EXIT} is set
(see {\tt rcclSetOptions(3)}).
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt ERange} --}
A motion queue size was specified that was either negative or
larger than {\tt MAX_MQ_ENTRIES}.

{\tt setMotionQueueSize()} will abort the program if called from the
control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt move(3)}, {\tt rcclSetOptions(3)}, {\tt errorStack(3)}.
\manEnd
\end

