/* vim: set ts=4 sw=4 tw=99 et:

 *

 * Copyright (C) 2004-2012 David Anderson

 *

 * This file is part of SourcePawn.

 *

 * SourcePawn 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 3 of the License, or (at your option)

 * any later version.

 * 

 * SourcePawn 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

 * SourcePawn. If not, see http://www.gnu.org/licenses/.

 */

#ifndef _include_sourcepawn2_api_h_

#define _include_sourcepawn2_api_h_

#include <assert.h>

#include <stddef.h>

#include "../include/keima_util.h"

namespace ke {

class Zone;

class Object;

class HandleScope;

class HeapRoot;

}

namespace Ke {

class Function;

class Package;

/*

 * A Handle is a safe pointer that holds an object reference, such that it

 * can be scanned and potentially moved by the garbage collector.

 */

template <typename T>

class Handle

{

    template <typename S> friend class Root;

  protected:

    template <typename S> void typeCheck() {

        while (false) {

            T *v1 = NULL;

            S *v2 = NULL;

            v1 = v2;

            (void)v1;

        }

    }

  public:

    Handle()

      : obj_(NULL)

    {

    }

    template <typename S> Handle(Handle<S> other)

      : obj_(reinterpret_cast<S *>(*other))

    {

        typeCheck<S>();

    }

    explicit Handle(T *obj)

      : obj_(obj)

    {

    }

    T *operator ->() const {

        return obj_;

    }

    T *operator *() const {

        return obj_;

    }

    operator bool () const {

        return !!obj_;

    }

  protected:

    T *obj_;

};

/*

 * A local variable that roots an object. Locals are owned by the nearest

 * HandleScope, and as soon as that HandleScope dies, all its Locals are

 * no longer available.

 */

template <typename T>

class Local : public Handle<T>

{

  public:

    Local()

      : Handle<T>()

    {

    }

    template <typename S> Local(Local<S> other)

      : Handle<T>(reinterpret_cast<T *>(*other))

    {

        this->template typeCheck<S>();

    }

    template <typename S> Local(S *other)

      : Handle<T>(other)

    {

    }

};

/*

 * A non-local variable that outlives HandleScopes. Unlike Local, a Root

 * actually represents a rooted location. Roots must be allocated and

 * disposed, and assignment to a root changes its contained object, not

 * the location of the object.

 */

template <typename T>

class Root

{

  public:

    Root()

      : root_(NULL)

    {

    }

    Root(Handle<T> other)

      : root_(NULL)

    {

        set(other);

    }

    inline ~Root();

    operator const Handle<T>() const {

        return obj_;

    }

    bool operator ==(Handle<T> other) {

        return Handle<T>(*this) == other;

    }

    Root<T> &operator =(Handle<T> other) {

        set(other);

        return *this;

    }

  private:

    void set(Handle<T> other);

    ke::HeapRoot *root_;

    Handle<T> obj_;

};

/*

 * A HandleScope is where Local roots are allcoated. When the HandleScope

 * is destroyed, all Handles created under it are also destroyed. HandleScopes

 * may only be allocated on the stack, in LIFO order.

 */

class HandleScope

{

  protected:

    ke::Zone *zone_;

    ke::Object **position_;

    HandleScope *prev_;

    HandleScope(ke::Zone *zone, ke::Object **position, HandleScope *prev)

      : zone_(zone),

        position_(position),

        prev_(prev)

    {

    }

  public:

    HandleScope();

    ~HandleScope();

    static ke::Object **CreateHandle(ke::Object *obj);

  private:

    // Disallow silly stuff.

    HandleScope(const HandleScope &);

    void operator =(const HandleScope &);

    void *operator new (size_t size);

    void operator delete(void *, size_t);

};

class Parameter;

// Error messages are pumped through this interface.

class IMessageReporter

{

  public:

    virtual void onOutOfMemory() {

    }

    virtual void onUncaughtException(const char *message) {

    }

    virtual void beginCompilationErrors(const char *file) {

    }

    virtual void reportCompilationError(const char *message, unsigned line, unsigned col) {

    }

    virtual void endCompilationErrors() {

    }

};

// For the purposes of error reporting, very basic information can be queried

// about the stack frame. This structure may be used to retrieve such

// information. During iteration, it is illegal to re-enter any scripted code

// or call any Keima functions that may cause garbage collection.

class IStackFrameIterator

{

  public:

    virtual ~IStackFrameIterator() {

    }

    // Returns true if there are more frames, false otherwise.

    virtual bool done() = 0;

    // Returns the name of the current function. This may be NULL if the

    // function is anonymous.

    virtual const char *function() = 0;

    // Returns the file of the current function. This will return an invalid

    // path for C++ functions (for example, "<native>").

    virtual const char *source() = 0;

    // Returns the line number currently executing on this frame. For C++

    // functions, this is always 0.

    virtual unsigned lineNumber() = 0;

    // Advance to the previous frame in the call stack.

    virtual void prev() = 0;

};

// Listener interface for when public functions are registered or unregisted.

class IPublicFunctionListener

{

  public:

    virtual ~IPublicFunctionListener() {

    }

    // Called when a public function becomes available to the runtime.

    virtual void registerPublic(Handle<Function> fun) = 0;

    // Called when a public is no longer available to the runtime.

    virtual void unregisterPublic(Handle<Function> fun) = 0;

};

// A string is an immutable UTF8 buffer.

class KE_EXPORT String

{

  public:

    static Local<String> NewAscii(const char *str);

    // Returns the length of the string, in bytes.

    unsigned length();

    // Returns the character buffer of the string, or NULL on failure. If the

    // string is interned, chars() is guaranteed to succeed.

    const char *chars();

};

// A function is an executable unit of code.

class KE_EXPORT Function

{

  public:

    // Returns the name of a function, which may be NULL. If not NULL, the

    // string is guaranteed to be interned.

    Local<String> name();

    // Returns the package the function was created in.

    Local<Package> package();

};

// A pubvar is an ISourcePawnEngine-compatible structure that holds information

// about public variables.

class KE_EXPORT Pubvar

{

  public:

    // Returns the name of a pubvar, which is never NULL. The string is

    // guaranteed to be interned.

    Local<String> name();

};

// A package is a collection of compiled files and possibly sub-packages.

// Internally, packages are used to implement the "import" statement. However,

// the host application can also create packages to organize related files,

// restrict import visibility, or implement hot swapping of loaded modules.

class KE_EXPORT Package

{

  public:

    enum {

        Normal = 0,

        // The package cannot be accessed from any import statement.

        Hidden = (1 << 0),

        // Source files compiled in this package cannot import names in the

        // package.

        Jailed = (1 << 1)

    };

    // Creates a package. The parent package may be NULL. The name can be NULL

    // as well. |path| must be a filesystem path, which will be normalized 

    // according to OS-specific rules.

    static Local<Package> New(Handle<Package> parent,

                              Handle<String> name,

                              const char *path,

                              unsigned flags);

    // Returns the name of the package, which may be NULL. The string is

    // guaranteed to be interned.

    Local<String> name();

    // Returns the full path of the package. The string is guaranteed to be

    // interned.

    Local<String> path();

    // Sets the package's native identity. This is a host-application defined

    // value that is passed to native callbacks.  Packages created under this

    // one will automatically inherit this native identity.

    void setNativeIdentity(void *identity);

    // Returns the package's native identity, or NULL if none was set.

    void *getNativeIdentity();

};

class Keima

{

  public:

    /*

     * Initializes the Keima engine. This must be called exactly once before any

     * other Keima functions are called. After this, it is safe to use Keima

     * on the calling thread only. It is not safe to race on calling this.

     */

    static bool Initialize();

    /*

     * Shuts down the Keima engine and frees data structures on all threads.

     */

    static void Shutdown();

    /*

     * Searches the call stack and returns true if the given package has any

     * active code running. This is an O(n) algorithm.

     */

    static bool IsInCallStack(Handle<Package> package);

    /*

     * Reclaim as much memory as possible. This pauses the calling thread

     * until garbage collection completes.

     */

    static void CollectGarbage();

    /*

     * Clear any pending exception.

     */

    static void ClearPendingException();

    /*

     * Executes a function with the given parameters. This interface is

     * intended for compatibility with SourceMod's ISourcePawnEngine2 and

     * should not be used otherwise, since it is intended to support only

     * a small subset of the core language.

     */

    static bool Invoke(Handle<Function> fun, const Parameter *params, unsigned nparams,

                       bool checkTypes, int *result);

    /*

     * Sets the global message handler through which errors will be reported

     */

    static void InstallMessageReporter(IMessageReporter *reporter);

    /* Returns a new stack frame iterator object. */

    static IStackFrameIterator *NewStackFrameIterator();

    /*

     * Binds a native, by name, to an address. Natives are an ISPE1 concept

     * (originally from Pawn/Small's AMX API). In SourceMod 1, natives were

     * registered globally, but bound to plugins individually. We roughly

     * preserve that functionality here, by allowing host applications to

     * give us the name -> address mappings.

     *

     * Natives can be rebound or unbound any number of times. This function

     * fails if there is not enough memory.

     */

    static bool BindNative(const char *name, void *address);

    /* Sets the object that will listen for public functions. */

    static void SetPublicFunctionListener(IPublicFunctionListener *listener);

    /*

     * Installs a system root folder. When an attempt to import locally fails,

     * the list of system roots are searched in the order they were installed.

     *

     * The given path must be absolute. It may contain a trailing slash.

     *

     * The name is an arbitrary, optional identifier that can be used to

     * build fully-qualified package identifiers.

     */

    static bool InstallSystemRoot(const char *path, const char *name);

    /*

     * Compiles a source file into a package and runs any initializers it has.

     * The file name must be a file name only, rather than a path. It may

     * optionally end in ".sp". If no ".sp" is provided, it is added

     * automatically.

     *

     * Note that if the file name (sans ".sp" extension) does not match the

     * regular expression /^[A-Za-z_][A-Za-z0-9_]+$/ then it will not be

     * importable from other files.

     */

    static bool Compile(Handle<Package> package, const char *name);

};

/*

 * Suppresses exceptions. This is useful for calling API functions. When this

 * in scope, errors will be reported, but the exception will be cleared after.

 */

class AutoClearExceptions

{

  public:

    ~AutoClearExceptions()

    {

        Keima::ClearPendingException();

    }

};

// Argument-passing interface for Invoke().

class Parameter

{

  public:

    enum Type {

        Int,

        Float,

        IntRef,

        FloatRef,

        Array,

        CharArray

    };

    Parameter()

    {

    }

    Parameter(int i)

      : type_(Int)

    {

        u.i = i;

    }

    Parameter(int *i, bool writeback)

      : type_(IntRef),

        writeback_(writeback)

    {

        u.ip = i;

    }

    Parameter(float f)

      : type_(Float)

    {

        u.f = f;

    }

    Parameter(float *f, bool writeback)

      : type_(FloatRef),

        writeback_(writeback)

    {

        u.fp = f;

    }

    Parameter(Type type, void *buffer, size_t length, bool writeback)

      : type_(type),

        writeback_(writeback),

        length_(length)

    {

        assert(type == Array || type == CharArray);

        u.buffer = buffer;

    }

    Type type() const {

        return type_;

    }

    int i32() const {

        assert(type() == Int);

        return u.i;

    }

    float f() const {

        assert(type() == Float);

        return u.f;

    }

    int *i32p() const {

        assert(type() == IntRef);

        return u.ip;

    }

    float *fp() const {

        assert(type() == FloatRef);

        return u.fp;

    }

    bool writeback() const {

        assert(type() >= IntRef && type() <= CharArray);

        return writeback_;

    }

    size_t length() const {

        return length_;

    }

    void *buffer() const {

        assert(type() == Array || type() == CharArray);

        return u.buffer;

    }

  private:

    Type type_;

    bool writeback_;

    size_t length_;

    union {

        int i;

        float f;

        int *ip;

        float *fp;

        void *buffer;

    } u;

};

class Internals

{

    template <typename T> friend class Root;

  private:

    static ke::HeapRoot *NewHeapRoot();

    static void Destroy(ke::HeapRoot *root);

};

template <typename T> void

Root<T>::set(Handle<T> other)

{

    if (!other) {

        obj_ = other;

        return;

    }

    ke::Object **ptr = reinterpret_cast<ke::Object **>(*other);

    if (!root_) {

        root_ = Internals::NewHeapRoot();

        if (!root_)

            return;

    }

    *reinterpret_cast<ke::Object **>(root_) = *ptr;

    obj_.obj_ = reinterpret_cast<T *>(root_);

}

template <typename T>

Root<T>::~Root()

{

    if (!root_)

        return;

    Internals::Destroy(root_);

}

}

#endif // _include_sourcepawn2_api_h_