source: trunk/src/script/qscriptengineagent.cpp@ 284

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the QtScript module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qscriptengineagent.h"

#ifndef QT_NO_SCRIPT

#include "qscriptvalue.h"
#include "qscriptengineagent_p.h"
#include "qscriptengine_p.h"
#include "qscriptcontext_p.h"
#include "qscriptmember_p.h"
#include "qscriptobject_p.h"
#include "qscriptvalueimpl_p.h"

QT_BEGIN_NAMESPACE

/*!
  \since 4.4
  \class QScriptEngineAgent

  \brief The QScriptEngineAgent class provides an interface to report events pertaining to QScriptEngine execution.

  \ingroup script
  \mainclass

  The QScriptEngineAgent class is the basis of tools that monitor and/or control the execution of a
  QScriptEngine, such as debuggers and profilers.

  To process script loading and unloading events, reimplement the
  scriptLoad() and scriptUnload() functions. scriptLoad() is called
  after the input to QScriptEngine::evaluate() has been parsed, right
  before the given script is executed. The engine assigns each
  script an ID, which is available as one of the arguments to
  scriptLoad(); subsequently, other event handlers can use the ID to
  identify a particular script. One common usage of scriptLoad() is
  to retain the script text, filename and base line number (the
  original input to QScriptEngine::evaluate()), so that other event
  handlers can e.g. map a line number to the corresponding line of
  text.

  scriptUnload() is called when the QScriptEngine has no further use
  for a script; the QScriptEngineAgent may at this point safely
  discard any resources associated with the script (such as the
  script text). Note that after scriptUnload() has been called, the
  QScriptEngine may reuse the relevant script ID for new scripts
  (i.e. as argument to a subsequent call to scriptLoad()).

  Evaluating the following script will result in scriptUnload()
  being called immediately after evaluation has completed:

  \snippet doc/src/snippets/code/src_script_qscriptengineagent.cpp 0

  Evaluating the following script will \b{not} result in a call to
  scriptUnload() when evaluation has completed:

  \snippet doc/src/snippets/code/src_script_qscriptengineagent.cpp 1

  The script isn't unloaded because it defines a function (\c{cube})
  that remains in the script environment after evaluation has
  completed. If a subsequent script removed the \c{cube} function
  (e.g. by setting it to \c{null}), scriptUnload() would be called
  when the function is garbage collected. In general terms, a script
  isn't unloaded until the engine has determined that none of its
  contents is referenced.

  To process script function calls and returns, reimplement the
  functionEntry() and functionExit() functions. functionEntry() is
  called when a script function is about to be executed;
  functionExit() is called when a script function is about to return,
  either normally or due to an exception.

  To process individual script statements, reimplement
  positionChange(). positionChange() is called each time the engine is
  about to execute a new statement of a script, and thus offers the
  finest level of script monitoring.

  To process exceptions, reimplement exceptionThrow() and
  exceptionCatch(). exceptionThrow() is called when a script exception
  is thrown, before it has been handled. exceptionCatch() is called
  when an exception handler is present, and execution is about to be
  resumed at the handler code.

  \sa QScriptEngine::setAgent(), QScriptContextInfo
*/

/*!
  \enum QScriptEngineAgent::Extension

  This enum specifies the possible extensions to a QScriptEngineAgent.

  \value DebuggerInvocationRequest The agent handles \c{debugger} script statements.

  \sa extension()
*/

QScriptEngineAgentPrivate::QScriptEngineAgentPrivate()
    : engine(0), q_ptr(0)
{
}

QScriptEngineAgentPrivate::~QScriptEngineAgentPrivate()
{
    QScriptEnginePrivate *eng_p = QScriptEnginePrivate::get(engine);
    eng_p->agentDeleted(q_ptr);
}

/*!
    Constructs a QScriptEngineAgent object for the given \a engine.

    The engine takes ownership of the agent.

    Call QScriptEngine::setAgent() to make this agent the active
    agent.
*/
QScriptEngineAgent::QScriptEngineAgent(QScriptEngine *engine)
    : d_ptr(new QScriptEngineAgentPrivate)
{
    d_ptr->q_ptr = this;
    d_ptr->engine = engine;
}

/*!
  \internal
*/
QScriptEngineAgent::QScriptEngineAgent(QScriptEngineAgentPrivate &dd, QScriptEngine *engine)
    : d_ptr(&dd)
{
    d_ptr->q_ptr = this;
    d_ptr->engine = engine;
}