shell/Platform.h

   1 /* -*- Mode: C++; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 4 -*- */
   2 /* vi: set ts=4 sw=4 expandtab: (add to ~/.vimrc: set modeline modelines=5) */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version
   7 * 1.1 (the "License"); you may not use this file except in compliance with
   8 * the License. You may obtain a copy of the License at
   9 * http://www.mozilla.org/MPL/
  10 *
  11 * Software distributed under the License is distributed on an "AS IS" basis,
  12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13 * for the specific language governing rights and limitations under the
  14 * License.
  15 *
  16 * The Original Code is [Open Source Virtual Machine.].
  17 *
  18 * The Initial Developer of the Original Code is
  19 * Adobe System Incorporated.
  20 * Portions created by the Initial Developer are Copyright (C) 2004-2006
  21 * the Initial Developer. All Rights Reserved.
  22 *
  23 * Contributor(s):
  24 *   Adobe AS3 Team
  25 *
  26 * Alternatively, the contents of this file may be used under the terms of
  27 * either the GNU General Public License Version 2 or later (the "GPL"), or
  28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29 * in which case the provisions of the GPL or the LGPL are applicable instead
  30 * of those above. If you wish to allow use of your version of this file only
  31 * under the terms of either the GPL or the LGPL, and not to allow others to
  32 * use your version of this file under the terms of the MPL, indicate your
  33 * decision by deleting the provisions above and replace them with the notice
  34 * and other provisions required by the GPL or the LGPL. If you do not delete
  35 * the provisions above, a recipient may use your version of this file under
  36 * the terms of any one of the MPL, the GPL or the LGPL.
  37 *
  38 * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef __Platform__
  41 #define __Platform__
  42
  43 #include "VMPI.h"
  44
  45 namespace avmshell
  46 {
  47     /**
  48     * function pointer for the timer callback function
  49     * @see setTimer()
  50     */
  51     typedef void (*AvmTimerCallback)(void*);
  52
  53     class File;
  54
  55     /**
  56     * Abstract base class representing the platform on which avm is ported to.
  57     * The class defines APIs that need to be implemented by the platform
  58     */
  59     class Platform
  60     {
  61     public:
  62         /**
  63         * Method to get access to the platform defined and created singleton
  64         * Required by the shell to call platform-specific implementations
  65         * @return Pointer to singleton instance of the platform defined implementation of this base class
  66         */
  67         static Platform* GetInstance();
  68
  69         /**
  70         * Virtual Destructor
  71         */
  72         virtual ~Platform() {}
  73
  74         /**
  75         * Method to terminate the shell application
  76         * A call to this method should never return
  77         * @param code  a numeric value indicating the result of program execution or an error code
  78         * @return none
  79         */
  80         virtual void exit(int code) = 0;
  81
  82         /**
  83         * Method to create a file handle to execute file I/O
  84         * The implementation should create a platform specific file instance
  85         * @return a handle to platform-specific file instance, NULL if an error occurred
  86         */
  87         virtual File* createFile() = 0;
  88
  89         /**
  90         * Method to destroy the file handle created via createFile
  91         * After this function is called the corresponding file handle becomes invalid
  92         * @param file file handle to be destroyed
  93         * @return none
  94         * @see createFile()
  95         */
  96         virtual void destroyFile(File* file) = 0;
  97
  98         /**
  99         * Method for setting up logging functionality
 100         * A platform can implement this method to open a file for logging messages
 101         * @param filename - name of the log file.  File name is UTF-8 encoded
 102         * @return none
 103         */
 104         virtual void initializeLogging(const char* filename) = 0;
 105
 106         /**
 107         * Method to write debug/log messages in a platform-defined way
 108         * The message is UTF-8 encoded
 109         * @param message - message to output
 110         * @return  number of bytes actually written
 111         * @see initializeLogging()
 112         */
 113         virtual int logMessage(const char* message) = 0;
 114
 115         /**
 116         * Method to receive a NUL-terminated string of user data via console or other source
 117         * This method is useful while running shell in interactive mode and for debugging purposes
 118         * Currently the expected encoding of the data is Latin-1
 119         * @param buffer buffer for storing the input data
 120         * @param bufferSize size of the buffer being passed indicating the max number of bytes it can accept
 121         * @return pointer to the beginning of input data, NULL on end-of-file
 122         */
 123         virtual char* getUserInput(char* buffer, int bufferSize) = 0;
 124
 125         /**
 126         * Method to retrieve the lowest address (the limit) of the program stack pointer
 127         * for the main program thread.  This function makes /no sense/ on any other thread.
 128         * The limit returned has been adjusted so that some amount of space is available
 129         * at addresses below the limit, for use by native code.
 130         *
 131         * The amount of space made available for native code will typically depend on the
 132         * platform class (64-bit, 32-bit, embedded), and is heuristic - we have no true
 133         * estimation at this time (now == Apr-2009) for how much space native code might need.
 134         *
 135         * The returned value is used by the VM execution engines to check heuristically
 136         * (and conservatively) for stack overflow.
 137         *
 138         * @return address indicating the lower limit of the current program's execution stack,
 139         *         less a safety margin.
 140         */
 141         virtual uintptr_t getMainThreadStackLimit() = 0;
 142
 143         /**
 144         * Method to set a platform-specific timer for a callback after specific interval of time
 145         * This method should implement a one-shot timer
 146         * @param seconds number of seconds indicating the timer expiration
 147         * @param callback function that will be invoked when the timer fires
 148         * @param callbackData context data that will be passed as an argument during "callback" invocation
 149         * @return none
 150         */
 151         virtual void setTimer(int seconds, AvmTimerCallback callback, void* callbackData) = 0;
 152     };
 153 }
 154
 155 #endif /* __Platform__ */