Skip to content

API

Jump to bottom Edit New page
Zwetan Kjukov edited this page Jun 16, 2016 · 4 revisions

Application Programming Interface

Essential read about the Redtamarin API.

It is ActionScript 3.0 but it is not Flash nor Adobe AIR.

Redtamarin is first the C/C++ source code that produce a runtime,
this is what we call the Redtamarin Shell or reshell.

  • the Flash Player is a runtime
    that execute inside a browser as a plugin
    and embed the playerglobal.swc
  • Adobe AIR is a runtime
    that execute at the operating system level
    like a GUI application (Outside of the browser)
    and embed the airglobal.swc
  • the Redtamarin Shell is a runtime
    that execute at the operating system level
    like a CLI program (command-line application,
    interactive shell, background service, etc.)
    and embed redtamarin.abc

The API is the second most important part of Redtamarin
and is defined by native code (implemented in C/C++) and
ActionScript 3.0 code organised in 3 layers

  • the C API
    in the C.* package
    see clib (the "C Library")
  • the Native API
    in the shell.* package
    see rnlib (the "Redtamarin Native Library")
  • the AVMGlue API
    in the flash.* and air.* packages
    see avmglue (the "Flash Platform API")

Important

The Redtamarin API is embedded in the runtime (redshell), that means you have access to it at all time without the need to load an external ABC library.

But that also means you can not override it (or some part of it) with your own implementation, without recompiling the runtime itself.

The following Design and API are not complete nor fully implemented but our philosophy and direction are very clear.

Design

The Redtamarin API design follow 3 simple principles

  • native implementations are very simple and low-level
  • ActionScript 3 builtins are used to organise the logic and glue the native
  • it is cross-platform as much as possible

The whole design is based on this prerogative

A good ActionScript 3.0 developer will be able
to reuse the API to write anything, high and low-level

We put the AS3 language upfront and center.

The C API

Combine definitions of the C Standard Library and POSIX to provide low-level native C functions and system call.

This is almost an opposite approach to Crossbridge.

With something like Crossbridge, the goal is to reuse C/C++ source code and make it available to the AS3 frontend to avoid to rewrite or port the C/C++ sources.

Our approach is to provide all the necessary C functions to the AS3 frontend, so a developer can write what he/she needs directly using the ActionScript 3.0 language.

For example: reading a file to a char array

with the C language

#include <stdlib.h>
#include <stdio.h>

char* buffer = 0;
long length;
FILE f* = fopen( "myfile.txt", "r" );

if( f )
{
    fseek( f, 0, SEEK_END );
    length = ftell( f );
    fseek( f, 0, SEEK_SET );
    buffer = (char*)malloc ((length+1)*sizeof(char));
    if( buffer )
    {
        fread( buffer, sizeof(char), length, f );
    }
    fclose( f );
}

buffer[length+1] = '\0';

with the AS3 language

import flash.utils.ByteArray;
import C.stdio.*;

var buffer:ByteArray;
var length:Number;
var f:FILE = fopen( "myfile.txt", "r" );

if( f )
{
    fseek( f, 0, SEEK_END );
    length = ftell( f );
    fseek( f, 0, SEEK_SET );
    buffer = new ByteArray();
    if( buffer )
    {
        fread( buffer, int(length), f );
    }
    fclose( f );
}

buffer.position = 0;

Both code are pretty similar, the Redtamarin API will not automatically translate or port the C for you but gives you all the tools to write a very similar code in AS3.

This is not perfect and will probably not works for all developers, as it requires to know and understand how to do things with the C language and implement it while knowing the subtle differences with the AS3 language (no use of pointers, no alloc/free of char array and use ByteArray instead, slight change in C function signatures, etc.).

Still, this C API is extremely powerful as it allows to write almost native functionalities without the need to compile native libraries or recompile the runtime.

A developer could write utilities and other libraries for the file system, socket, and other native-like libraries like database drivers etc.

The Native API

Provides native functionalities implemented in C/C++ that can not fit in the C API or be replicated in AS3, and also provides AS3 implementation (reusing the C API) of essential API.

This is a higher-level API which can provide complex implementations while preserving the cross-platform nature of the API.

For example, for the essential functionality of "reading a file", see the implementation of FileSystem.read().

Thanks to the C API we can provide an implementation using only the AS3 language, this is our "default" API to do the essential like working with the file system.

It would not be very convenient to force the developers to implement such basic functionality using the C API all the time, so we already made one implementation for them.

But some more advanced developers may want to build such default functionality themselves, as "writing their own API", and then they can also do that by reusing the C API.

The other use case of the Redtamarin Native API is to implement complex native functionalities in a cross-platform way.

For example, to manage user and group, the Windows API is not the same as the UNIX API (source: MSDN - UNIX Application Migration Guide, which is nowhere to be found anymore).

If we wanted to add the functionality "adding a user to a group"

  • Linux would use getgrnam() and getpwnam()
  • Windows would use NetLocalGroupAddMembers()
  • Mac OS X may reuse the Linux functionalities or use yet something else

To implement such functionalities we may end up implementing an ActionScript 3.0 SystemSecurity class with the method addUserToGroup() which detect the system and reroute to the correct native function under the hood.

In general, wether the implementation is native in C/C++ or in AS3, the Native API provide a unified API for essential functionalities.

Note:
Currently we have a FileSystem class to work with the file system,
but we don't have yet a SocketSystem class to work with sockets
and as a developer you are forced to use the low-level C API socket functions.

The AVMGlue API

Provides an open source implementation of the Flash Platform API.

This is a convenient API, eg. nice to have, written in AS3 and reusing extensively either the C API or the Native API, while trying to avoid to implement code in C/C++ (it could happen if needed).

The Adobe Team made us numerous gift in their implementation of Avmplus (known before as project Tamarin) as we can reuse more than the just the basic AS3 builtins.

For example: the ByteArray class, the Proxy class, the Worker class, etc.

Our current focus is on what we consider the most essential like the flash.utils.*, flash.filesystem.*, and flash.net.* packages.

Our biggest challenge is to nicely integrate the notion of workers (multi-threads programming) with the management of events (asynchronous programming).

Evolution

If later we need or want to integrate (or reuse) "bigger" native libraries into the runtime, we will focus mainly on extending the C API.

For example, if we wanted to integrate the zlib library to add the functionality to zip and unzip files, we would probably provide access to the zlib native function trough the C.zlib.* package, and then maybe provide a higher-level API written in AS3 in the Native API for convenience (Data.zip(), Data.unzip(), etc.).

Another option would be to be able to load dynamically in-memory a pre-compiled library and associate to it an AS3 API.

For now, if you want to use a "zip library" you will need to implement it yourself or reuse one already implemented in ActionScript 3.0, see for example: src/utils/abcdis/zip/ZipFile.as.

Convention

In General

  • we stick to our API design principles
  • all implementations should be cross-platform
    for Windows, Mac OS X and Linux
    • if not possible the documentation
      should clearly mark the availability of the API
    • if not available the API functionality
      should be a "no-op" (No Operation)
      and not an Error
  • as long as we don't reach v1.0 stable
    we can change everything
    • API availability
    • function signatures
    • boot sequence logic
    • break backward compatibility
  • to hide or extend some parts of the API
    we use the AVM2 namespace
  • we have 3 layers of API
    but we consider all API available at all time
    • the C API may use some of the Native API or AVMGlue API
    • the AVMGlue API may be extended with API not available to the Flash Platform API
    • some API may be "dynamic" in the sense
      change their behaviour based on the environment,
      operating system, resources availability, etc.

The C API

  • we do not use pointers
    but we can pass around Object reference
  • we use AS3 ByteArray in place of the C char array
  • we use AS3 String in place of C const char
  • constant definitions are not hardcoded in AS3
    but "extracted" as getters from the native header files
  • if a C function is not implemented
    we create/return an error ENOSYS - Function not implemented
    we do not throw an Error or CErrror
  • if a C function is a "no-op" (No Operation)
    we do not create/return an errno
    and silently fail or do nothing
  • we encourage "defensive programming"
    eg. strict validation of arguments (this can throw errors)
  • we avoid to use memory allocation/free functions
  • we avoid to use functions that could break the workers (multi-threads)

The Native API

  • we encourage the same "defensive programming"
  • while reusing the C API if a C error occurs
    we throw a CError (Error wrapper for errno)
  • if a functionality is not implemented
    we throw a NotImplementedError
  • if a functionality is a "no-op" (No Operation)
    we do not throw and instead silently fail or do nothing
  • we do not use Event but function callback by default

The AVMGlue API

  • all the same rules of the Native API applies
  • we try to maintain the same API signatures as the Flash Platform API
    but some special cases could require exceptions or extensions
Add a custom footer
Add a custom sidebar
Clone this wiki locally