path: root/lib/command_queue.c

/* Command Message Queue
 * Copyright (C) 2009 Chris Hall (GMCH), Highwayman
 *
 * This file is part of GNU Zebra.
 *
 * GNU Zebra 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 2, or (at your
 * option) any later version.
 *
 * GNU Zebra 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 GNU Zebra; see the file COPYING.  If not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */
#include "misc.h"

#include "qpnexus.h"
#include "mqueue.h"
#include "thread.h"

#include "command_queue.h"
#include "command_execute.h"
#include "vty_command.h"
#include "vty_io.h"
#include "log.h"

/*==============================================================================
 * This command loop processes commands for VTY_TERMINAL and VTY_SHELL_SERVER.
 *
 * The command loop is a form of co-routine, which is "called" by sending a
 * message (or by legacy threads events).  In the multi-pthread world, the
 * command loop may run in either the vty_cli_nexus or the vty_cmd_nexus, and
 * may be passed from one to the other by sending a message.
 *
 * The command loop is usually in one of three states:
 *
 *   vc_running   -- the command loop is running, doing things.
 *
 *                   In this state the vty  and the vty->exec are in the hands
 *                   of the command loop.
 *
 *                   The vty->vio is always accessed under VTY_LOCK().
 *
 *                   Note that one of the things the command loop may be
 *                   doing is waiting for a message to be picked up (or
 *                   a legacy thread event to be dispatched).
 *
 *   vc_waiting   -- the command loop is waiting for something to happen
 *                   (typically some I/O), and will stay there until a
 *                   message is sent (or a legacy threads event).
 *
 *                   To be waiting the command loop must have entered "hiatus"
 *                   and then exited.
 *
 * When a command loop is or has been stopped, to goes to vc_stopped state.
 *
 * There are further issues:
 *
 *   * In the mult-pthreaded world, commands may be parsed in either pthread,
 *     but most are executed in the Routing thread.  So may switch pthreads
 *     after parsing a command -- by sending a message.
 *
 *   * opening pipes is done in the vty_cli_nexus, in case of any possible
 *     blocking and because the pselect() stuff is all done in the
 *     vty_cli_nexus.
 *
 *   * all output is via fifo buffers -- when output is pushed, as much as
 *     possible is done immediately, but if necessary the pselect() process
 *     (in the vty_cli_nexus) is left to keep things moving.
 *
 *     In vty_io_basic() it is possible to set read/write ready and associated
 *     timeouts while running in the vty_cmd_nexus, but note that this is done
 *     by sending messages to the CLI thread (if multi-pthreaded).
 *
 * The smooth running of the command handling depends on the continued
 * running of the CLI thread.
 *
 * To close a VTY must (eventually) arrange for the state to not be vc_running.
 * While a vty is vc_running, the command loop may be in either nexus, and
 * may be:
 *
 *   - on the vty_cli_nexus queue                  (or the combined queue)
 *   - executing cq_process() in the vty_cli_nexus (or the single "both" nexus)
 *   - on the vty_cmd_nexus queue                  (if different)
 *   - executing cq_process() in the vty_cmd_nexus (if different)
 *
 * where being on the queue means that there is a message waiting to be
 * picked up on that queue, which will end up calling cq_process().
 *
 * Or, in the legacy threads world:
 *
 *   - on the event queue  -- waiting for event handler to call cq_process()
 *   - executing cq_process()
 *
 * To bring the command loop to a stop will call cq_revoke to revoke any
 * pending message or pending legacy event.  If that succeeds, then the
 * command loop can be stopped immediately.  If not, then vc_running implies
 * it is executing in cq_process() in one of the nexuses.
 */

/*------------------------------------------------------------------------------
 * Prototypes
 */
static void cq_enqueue(struct vty *vty, qpn_nexus dst, cmd_exec_state_t state,
                                                       cmd_return_code_t ret) ;
static void cq_action(mqueue_block mqb, mqb_flag_t flag);
static int cq_thread(struct thread* thread) ;
static void cq_process(vty vty, cmd_exec_state_t state, cmd_return_code_t ret) ;

/*------------------------------------------------------------------------------
 * Enqueue vty to enter the command loop -- must be exec_null
 *
 * Expects the vty start up process to have output some cheerful messages,
 * which is treated as a dummy "login" command.  So the loop is entered at
 * "exec_done_cmd", which will push out the output, deal with the return code,
 * and loop round to fetch the first command line (if required).
 */
extern void
cq_loop_enter(vty vty, cmd_return_code_t ret)
{
  VTY_ASSERT_CLI_THREAD() ;

  qassert(vty->exec->state == exec_null) ;

  cq_enqueue(vty, vty_cli_nexus, exec_done_cmd, ret) ;
} ;

/*------------------------------------------------------------------------------
 * Continue (resume) at hiatus -- must be exec_hiatus
 */
extern void
cq_continue(vty vty, cmd_return_code_t ret)
{
  VTY_ASSERT_CLI_THREAD() ;

  qassert(vty->exec->state == exec_hiatus) ;

  cq_enqueue(vty, vty_cli_nexus, exec_hiatus, ret) ;
} ;

/*------------------------------------------------------------------------------
 * Enqueue vty for execution in given nexus or issue thread event.
 *
 * Will execute in the current exec->state, passing in the given return
 * code.
 *
 * Note that the vio->state *must* be vc_running.
 */
static void
cq_enqueue(vty vty, qpn_nexus dst, cmd_exec_state_t state,
                                   cmd_return_code_t ret)
{
  cmd_exec exec = vty->exec ;

  qassert((dst == vty_cli_nexus) || (dst == vty_cmd_nexus)) ;

  exec->locus = dst ;
  exec->state = state ;
  exec->ret   = ret ;

  if (vty_nexus)
    {
      mqueue_block mqb ;

      if ((mqb = exec->cq.mqb) == NULL)
        mqb = exec->cq.mqb = mqb_init_new(NULL, cq_action, vty) ;

      mqueue_enqueue(dst->queue, mqb, (dst == vty_cmd_nexus) ? mqb_priority
                                                             : mqb_ordinary) ;
    }
  else
    {
      qassert(vty_cli_nexus == vty_cmd_nexus) ;
      exec->cq.thread = thread_add_event(vty_master, cq_thread, vty, 0) ;
    } ;
} ;

/*------------------------------------------------------------------------------
 * Deal with command message -- in the qpthreads world.
 *
 * Note that if the message is revoked, then the state is set vc_stopped.
 * We revoke when stopping a command loop -- see cq_revoke, below.  If the
 * message is revoked at any other time then the command loop is, indeed,
 * stopped -- the I/O side may plow on until buffers empty, but the
 * command loop will not cq_continue().  At
 */
static void
cq_action(mqueue_block mqb, mqb_flag_t flag)
{
  vty   vty;

  assert(vty_nexus) ;                   /* must be running qnexus-wise  */

  vty  = mqb_get_arg0(mqb);

  qassert(vty->exec->cq.mqb == mqb) ;

  if (flag == mqb_action)
    cq_process(vty, vty->exec->state, vty->exec->ret) ;
                                       /* do not touch vty on way out   */
  else
    {
      /* Revoke action.                                                 */
      mqb_free(mqb) ;
      vty->exec->cq.mqb = NULL ;

      vty_cmd_set_stopped(vty) ;        /* enforced stop of loop        */
    } ;
} ;

/*------------------------------------------------------------------------------
 * Deal with command message -- in the legacy threads world.
 */
static int
cq_thread(struct thread* thread)
{
  vty   vty = THREAD_ARG(thread) ;

  qassert(vty->exec->cq.thread == thread) ;

  vty->exec->cq.thread = NULL ;

  cq_process(vty, vty->exec->state, vty->exec->ret) ;
                                        /* do not touch vty on way out  */
  return 0 ;
} ;

/*------------------------------------------------------------------------------
 * Process command(s) queued from VTY_TERMINAL or from VTY_SHELL_SERVER.
 *
 * This is essentially a coroutine, where the state is in the vty, noting that:
 *
 *   vty->exec->state   is the "return address"
 *   vty->exec->ret     is the "return code"
 *
 * The command loop runs at the mqueue level in the qpnexus world, or is
 * driven by "events" in the legacy threads world.  The two ways into the
 * loop are:
 *
 *   cq_loop_enter()   -- called once and once only to start the loop.
 *
 *   cq_continue()     -- called when some I/O process has completed and
 *                        the loop is in hiatus, waiting for I/O.
 *
 * The one way out of the loop is when it hits a hiatus, which is triggered
 * by any operation not returning CMD_SUCCESS.  In hiatus, vty_cmd_hiatus()
 * is called and given the current return code to deal with.  It will
 * return:
 *
 *    CMD_SUCCESS   => can proceed to fetch the next command
 *    CMD_WAITING   => must leave the command loop, waiting for I/O
 *    CMD_STOP      => close the vty and leave command loop
 *    CMD_IO_ERROR  => loop back and deal with the error
 *
 * The cq_loop_enter() and cq_continue() operations send a message (to the
 * cli thread, in the mult-pthreaded world), whose action routine is to call
 * cq_process().
 *
 * In the multi-pthreaded world, opening and closing files MUST be done in the
 * cli thread.  Most commands MUST be executed in the cmd thread.  So the
 * command loop is passed between the threads in a number of places.  (To keep
 * life simple, switches back to the cli thread if ends up waiting for I/O.)
 *
 * The vty_io_basic stuff allows the multi-pthread vty_cmd_nexus to set read
 * and/or write ready state -- which may generate messages to the
 * vty_cli_nexus.
 *
 * NB: on exit from cq_process the VTY may have been closed down and released,
 *     so do NOT depend on its existence.
 */
static void
cq_process(vty vty, cmd_exec_state_t state, cmd_return_code_t ret)
{
  cmd_exec    exec   = vty->exec ;
  cmd_parsed  parsed = exec->parsed ;

  /* Have switch wrapped in a while(1) so that can change state by setting
   * exec->state and doing "continue".
   *
   * Breaking out of the switch forces the exec state to exec_hiatus,
   * with the current ret (which will switch to the CLI thread).
   *
   * The exec locus is either vty_cli_nexus or vty_cmd_nexus.  If these
   * are equal (including both NULL, in the legacy threads world), then is
   * running single threaded -- otherwise is running multi-threaded.
   */
  while (1)
    {
     switch(state)
      {
        /*--------------------------------------------------------------------
         * Should not get here in exec_null state.
         */
        case exec_null:
          zabort("exec state == exec_null") ;
          break ;

        /*--------------------------------------------------------------------
         * Need another command to execute => in_pipe !
         *
         * If multi-threaded: may be in either thread.  If vty_cmd_fetch_line()
         * cannot, for any reason, return a command line, will return something
         * other than CMD_SUCCESS -- which enters the exec_hiatus.
         */
        case exec_fetch:
          ret = vty_cmd_fetch_line(vty) ;

          if (ret != CMD_SUCCESS)
            break ;

          if (exec->action->to_do != cmd_do_command)
            {
              state = exec_special ;
              continue ;
            } ;

          fall_through ;                /* with ret == CMD_SUCCESS      */

        /*--------------------------------------------------------------------
         * Parse command in hand
         *
         * If multi-threaded: may be in either thread.
         */
          cmd_tokenize(parsed, exec->action->line, exec->context->full_lex) ;

          ret = cmd_parse_command(parsed, exec->context) ;
          if (ret != CMD_SUCCESS)
            {
              if (ret != CMD_EMPTY)
                break ;         /* stop on *any* parsing issue          */

              /* Empty lines from in_pipes we simply ignore.
               *
               * Don't expect to see them otherwise, but if we do then need
               * to complete the command execution process.
               */
              ret = CMD_SUCCESS ;

              state = exec_done_cmd ;
              continue ;
            } ;

          /* reflection now                                             */
          if (exec->reflect)
            {
              ret = vty_cmd_reflect_line(vty) ;

              if ((ret != CMD_SUCCESS) && (ret != CMD_WAITING))
                break ;         /* CMD_IO_ERROR or CMD_HIATUS           */
            } ;

          fall_through ;

        /*--------------------------------------------------------------------
         * Pipe work if any
         *
         * Will receive CMD_EOF if the VTY has been closed.
         *
         * If multi-threaded: must be in vty_cli_nexus to proceed -- so may
         * generate message to transfer to vty_cli_nexus.
         */
        case exec_open_pipes:
          if ((parsed->parts & cmd_parts_pipe) != 0)
            {
              /* If running pthreaded, do open pipes in vty_cli_nexus   */
              if (exec->locus != vty_cli_nexus)
                return cq_enqueue(vty, vty_cli_nexus, exec_open_pipes, ret) ;

              /* Now in vty_cli_nexus                                   */
              ret = cmd_open_pipes(vty) ;
              if (ret != CMD_SUCCESS)
                break ;                 /* quit if open fails           */
            } ;

          fall_through ;                /* with ret == CMD_SUCCESS      */

        /*--------------------------------------------------------------------
         * Execute command in hand (if any)
         *
         * If multi-threaded: some commands can run in either thread, most must
         * run in the vty_cmd_nexus -- so may generate message to transfer to
         * the vty_cmd_nexus.
         */
        case exec_execute:
          if ((parsed->parts & cmd_part_command) != 0)
            {
              /* If running pthreaded, do most commands in vty_cmd_nexus  */
              if ((exec->locus != vty_cmd_nexus) && (!cmd_is_direct(parsed)))
                return cq_enqueue(vty, vty_cmd_nexus, exec_execute, ret) ;

              /* Standard command handling                              */
#ifdef CONSUMED_TIME_CHECK
              {
                  RUSAGE_T before;
                  RUSAGE_T after;
                  unsigned long realtime, cputime;

                  GETRUSAGE(&before);
#endif /* CONSUMED_TIME_CHECK */

                  ret = cmd_execute(vty) ;

#ifdef CONSUMED_TIME_CHECK
                  GETRUSAGE(&after);
                  realtime = thread_consumed_time(&after, &before, &cputime) ;
                  if (realtime > CONSUMED_TIME_CHECK)
                    /* Warn about CPU hog that must be fixed. */
                    zlog(NULL, LOG_WARNING,
                        "SLOW COMMAND: command took %lums (cpu time %lums): %s",
                                        realtime/1000, cputime/1000,
                                        qs_make_string(exec->action->line)) ;
              } ;
#endif /* CONSUMED_TIME_CHECK */
            } ;

          fall_through ;

        /*--------------------------------------------------------------------
         * Command has completed -- if successful, push output and loop back
         * to fetch another command.
         *
         * Break if not successful, or push fails or must wait.
         *
         * If multi-threaded: may be in either thread:
         *
         *   vty_cmd_success() may set write ready -- so in vty_cmd_nexus may
         *   generate message to vty_cli_nexus.
         */
        case exec_done_cmd:
          if (ret == CMD_SUCCESS)
            ret = vty_cmd_success(vty) ;

          if ((ret != CMD_SUCCESS) && (ret != CMD_WAITING))
            break ;                     /* stop                         */

          state = exec_fetch ;
          continue ;

        /*--------------------------------------------------------------------
         * Deal with the "special" commands
         */
        case exec_special:
          if (exec->locus != vty_cli_nexus)
            return cq_enqueue(vty, vty_cli_nexus, exec_special, ret) ;

          ret = vty_cmd_special(vty) ;
          if (ret != CMD_SUCCESS)
            break ;

          state = exec_done_cmd ;
          continue ;

        /*--------------------------------------------------------------------
         * Hiatus state -- some return code to be dealt with !
         *
         * If we are not in the vty_cli_nexus, then must pass the problem
         * to the vty_cli_nexus.  If the return code is CMD_STOP, or there
         * is a CMD_STOP signal, then drop the config symbol of power -- see
         * uty_close().
         */
        case exec_hiatus:
          if (exec->locus != vty_cli_nexus)
            {
              vty_cmd_check_stop(vty, ret) ;
              return cq_enqueue(vty, vty_cli_nexus, exec_hiatus, ret) ;
            } ;

          while (1)
            {
              /* Let vty_cmd_hiatus() deal with the return code and/or any
               * stop/error/etc trap, and adjust the stack as required.
               */
              ret = vty_cmd_hiatus(vty, ret) ;

              if (ret == CMD_SUCCESS)
                break ;                 /* back to exec_fetch           */

              if (ret == CMD_WAITING)
                {
                  exec->state = exec_hiatus ;
                  return ;              /* <<< DONE, pro tem            */
                } ;

              if (ret == CMD_IO_ERROR)
                continue ;              /* give error back to hiatus    */

              if (ret == CMD_STOP)
                {
                  exec->state = exec_stopped ;
                  vty_cmd_loop_exit(vty) ;

                  return ;              /* <<< DONE, permanently        */
                } ;

              zabort("invalid return from vty_cmd_hiatus()") ;
            } ;

          state = exec_fetch ;
          continue ;                    /* can fetch, again             */

        /*--------------------------------------------------------------------
         * Should not get here in exec_stopped state.
         */
        case exec_stopped:
          zabort("exec state == exec_exit") ;
          break ;

        /*----------------------------------------------------------------------
         * Unknown exec->state !
         */
        default:
          zabort("unknown exec->state") ;
          break ;
      } ;

      /* Have broken out of the switch() => exec_hiatus                 */
      state = exec_hiatus ;
    } ;
} ;

/*------------------------------------------------------------------------------
 * Revoke any message associated with the given vty from the command queue.
 *
 * This is used when a VTY_TERMINAL or a VTY_SHELL_SERVER is being closed.
 *
 * See cq_process above for discussion of what messages there may be.  At any
 * time there is at most one message in flight.
 *
 * In the single-threaded world (including legacy threads), messages or events
 * are used to enter or resume the command loop.  If a message or event can
 * be revoked, then the command loop is effectively stopped.
 *
 * In the multi-threaded world, messages are used to enter or resume the
 * command loop, and to transfer it to and from the cli and cmd threads.  If
 * a message can be revoked, the command loop is effectively stopped.
 *
 * Note that the revoke does not affect any vty_cli_nexus messages associated
 * with the vty_io_basic operations.
 *
 * If succeeds in revoking, then will have set the state to vc_stopped, and
 * will have released the message block or legacy thread object.
 *
 * Returns:  true <=> have revoked a pending message/event
 *
 * NB: if no command loop has ever been started for this vty, then will not
 *     find anything to revoke.
 */
extern bool
cq_revoke(vty vty)
{
  int ret ;

  VTY_ASSERT_CLI_THREAD_LOCKED() ;

  if (vty_nexus)
    {
      ret = mqueue_revoke(vty_cli_nexus->queue, vty, 1) ;

      if ((ret == 0) && vty_multi_nexus)
        ret = mqueue_revoke(vty_cmd_nexus->queue, vty, 1) ;
    }
  else
    {
      ret = thread_cancel_event(vty_master, vty) ;

      if (ret != 0)
        {
          /* Make sure in same state as after mqueue_revoke.            */
          vty_cmd_set_stopped(vty) ;
          vty->exec->cq.thread = NULL ;
        } ;
    } ;

  /* If revoked message/event, the command loop is stopped.             */
  if (ret != 0)
    vty->exec->state = exec_stopped ;

  return (ret != 0) ;
} ;