Swfdec - Jun 2007 - Branch 'as' - 3 commits - doc/Makefile.am doc/swfdec-docs.sgml doc/swfdec-sections.txt libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h

doc/Makefile.am               |    1 
 doc/swfdec-docs.sgml          |    2 
 doc/swfdec-sections.txt       |   39 +++++++++++
 libswfdec/swfdec_as_context.c |  139 +++++++++++++++++++++++++++++++++++-------
 libswfdec/swfdec_as_context.h |    5 -
 5 files changed, 160 insertions(+), 26 deletions(-)

New commits:
diff-tree 2203783339a0ece4ce8d264d0ec28c77034c3288 (from
bc23ec80d8afa3d49618a6b180ace50f7c7b19f3)
Author: Benjamin Otte <otte at gnome.org>
Date:   Fri Jun 29 02:00:55 2007 +0200

    add an internals/garbage collection section and a stub for documenting
SwfdecAsContext

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f43e706..ce3ae3a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -56,6 +56,7 @@ IGNORE_HFILES= \
 	jpeg \
 	swfdec_amf.h \
 	swfdec_as_interpret.h \
+	swfdec_as_math.h \
 	swfdec_as_number.h \
 	swfdec_as_string.h \
 	swfdec_as_strings.h \
diff --git a/doc/swfdec-docs.sgml b/doc/swfdec-docs.sgml
index 07c7ee4..537817a 100644
--- a/doc/swfdec-docs.sgml
+++ b/doc/swfdec-docs.sgml
@@ -22,6 +22,8 @@
   </chapter>
   <chapter>
     <title>Actionscript interpreter</title>
+    <xi:include href="xml/Internals.xml"/>
     <xi:include href="xml/SwfdecAsValue.xml"/>
+    <xi:include href="xml/SwfdecAsContext.xml"/>
   </chapter>
 </book>
diff --git a/doc/swfdec-sections.txt b/doc/swfdec-sections.txt
index 4d93f11..d147bdd 100644
--- a/doc/swfdec-sections.txt
+++ b/doc/swfdec-sections.txt
@@ -180,6 +180,14 @@ SWFDEC_TYPE_GTK_LOADER
 </SECTION>
 
 <SECTION>
+<FILE>Internals</FILE>
+<TITLE>Internals</TITLE>
+swfdec_as_object_mark
+swfdec_as_string_mark
+swfdec_as_value_mark
+</SECTION>
+
+<SECTION>
 <FILE>SwfdecAsValue</FILE>
 <TITLE>SwfdecAsValue</TITLE>
 SwfdecAsValueType
@@ -212,3 +220,34 @@ SWFDEC_AS_VALUE_IS_STRING
 SWFDEC_AS_VALUE_IS_NULL
 SWFDEC_AS_VALUE_IS_OBJECT
 </SECTION>
+
+<SECTION>
+<FILE>SwfdecAsContext</FILE>
+<TITLE>SwfdecAsContext</TITLE>
+swfdec_as_context_abort
+swfdec_as_context_abort_oom
+swfdec_as_context_eval
+swfdec_as_context_eval_set
+swfdec_as_context_gc
+swfdec_as_context_get_string
+swfdec_as_context_get_time
+swfdec_as_context_give_string
+swfdec_as_context_maybe_gc
+swfdec_as_context_new
+swfdec_as_context_return
+swfdec_as_context_run
+swfdec_as_context_startup
+swfdec_as_context_trace
+swfdec_as_context_unuse_mem
+swfdec_as_context_use_mem
+<SUBSECTION Standard>
+swfdec_as_context_get_type
+SwfdecAsContextClass
+SWFDEC_AS_CONTEXT
+SWFDEC_AS_CONTEXT_CLASS
+SWFDEC_AS_CONTEXT_GET_CLASS
+SWFDEC_IS_AS_CONTEXT
+SWFDEC_IS_AS_CONTEXT_CLASS
+SWFDEC_TYPE_AS_CONTEXT
+</SECTION>
+
diff-tree bc23ec80d8afa3d49618a6b180ace50f7c7b19f3 (from
677831ce294814177191a5950e5320efb73d6e3d)
Author: Benjamin Otte <otte at gnome.org>
Date:   Fri Jun 29 02:00:34 2007 +0200

    add lots of documentation

diff --git a/libswfdec/swfdec_as_context.c b/libswfdec/swfdec_as_context.c
index 8e06f31..0037932 100644
--- a/libswfdec/swfdec_as_context.c
+++ b/libswfdec/swfdec_as_context.c
@@ -38,7 +38,71 @@
 #include "swfdec_debug.h"
 #include "swfdec_script.h"
 
-/*** GTK_DOC ***/
+/*** GARBAGE COLLECTION DOCS ***/
+
+/**
+ * SECTION:Internals
+ * @title: Internals and garbage collection
+ * @short_description: understanding internals such as garbage collection
+ * @see_also: #SwfdecAsContext
+ *
+ * This section deals with the internals of the Swfdec Actionscript engine. You
+ * should probably read this first when trying to write code with it. If
you're
+ * just trying to use Swfdec for creating Flash content, you can probably skip
+ * this section.
+ *
+ * First, I'd like to note that the Swfdec script engine has to be modeled
very
+ * closely after the existing Flash players. So if there are some behaviours
+ * that seem stupid at first sight, it might very well be that it was chosen
for
+ * a very particular reason. Now on to the features.
+ *
+ * The Swfdec script engine tries to imitate Actionscript as good as possible.
+ * Actionscript is similar to Javascript, but not equal. Depending on the 
+ * version of the script executed it might be more or less similar. An
important
+ * example is that Flash in versions up to 6 did case-insensitive variable 
+ * lookups.
+ *
+ * The script engine starts its life when it is initialized via 
+ * swfdec_as_context_startup (). At that point, the basic objects are created.
+ * After this function has been called, you can start executing code. All code
+ * execution happens by creating a new #SwfdecAsFrame and then calling 
+ * swfdec_as_context_run () to execute it. This function is the single entry 
+ * point for code execution. Convenience functions exist that make executing 
+ * code easy, most notably swfdec_as_object_run() and 
+ * swfdec_as_object_call().
+ *
+ * It is also easily possible to extend the environment by adding new objects.
+ * In fact, without doing so, the environment is pretty bare as it just
contains
+ * the basic Math, String, Number, Array, Date and Boolean objects. This is
done
+ * by adding #SwfdecAsNative functions to the environment. The easy way
+ * to do this is via swfdec_as_object_add_function().
+ *
+ * The Swfdec script engine is dynamically typed and knows about different
types
+ * of values. See #SwfdecAsValue for the different values. Memory management is
+ * done using a mark and sweep garbage collector. You can initiate a garbage 
+ * collection cycle by calling swfdec_as_context_gc() or 
+ * swfdec_as_context_maybe_gc(). You should do this regularly to avoid
excessive
+ * memory use. The #SwfdecAsContext will then collect the objects and strings
it
+ * is keeping track of. If you want to use an object or string in the script 
+ * engine, you'll have to add it first via swfdec_as_object_add() or
+ * swfdec_as_context_get_string() and swfdec_as_context_give_string(), 
+ * respectively.
+ *
+ * Garbage-collected strings are special in Swfdec in that they are unique.
This
+ * means the same string exists exactly once. Because of this you can do 
+ * equality comparisons using == instead of strcmp. It also means that if you 
+ * forget to add a string to the context before using it, your app will most 
+ * likely not work, since the string will not compare equal to any other
string.
+ *
+ * When a garbage collection cycle happens, all reachable objects and strings 
+ * are marked and all unreachable ones are freed. This is done by calling the
+ * context class's mark function which will mark all reachable objects.
This is
+ * usually called the "root set". For any reachable object, the
object's mark
+ * function is called so that the object in turn can mark all objects it can 
+ * reach itself. Marking is done via functions described below.
+ */
+
+/*** GTK-DOC ***/
 
 /**
  * SwfdecAsContextState
@@ -58,6 +122,15 @@
 
 /*** RUNNING STATE ***/
 
+/**
+ * swfdec_as_context_abort:
+ * @context: a #SwfdecAsContext
+ * @reason: a string describing why execution was aborted
+ *
+ * Aborts script execution in @context. Call this functon if the script engine 
+ * encountered a fatal error and cannot continue. A possible reason for this is
+ * an out-of-memory condition.
+ **/
 void
 swfdec_as_context_abort (SwfdecAsContext *context, const char *reason)
 {
@@ -78,22 +151,8 @@ swfdec_as_context_abort (SwfdecAsContext
  *
  * Registers @bytes additional bytes as in use by the @context. This function
  * keeps track of the memory that script code consumes. If too many memory is 
- * in use, this function may decide to abort execution with an out of memory 
- * error. It may also invoke the garbage collector to free unused memory. Note
- * that running the garbage collector is a potentially dangerous operation,
- * since the calling code must ensure that all memory is reachable for the 
- * garbage collector. Consider the following innocent looking code:
- * <informalexample><programlisting>SwfdecAsValue *v =
swfdec_as_stack_pop (stack);
- * SwfdecAsObject *object = swfdec_as_object_new (context);
- * swfdec_as_object_set (object, swfdec_as_context_get_string (context,
"something"), v);
- * </programlisting></informalexample>
- * This code may cause the value stored in v to be lost, as it is not reachable
- * when swfdec_as_object_new() invokes the garbage collector. Because of this,
- * all functions in the Actionscript engine that might invoke the garbage 
- * collector contain this warning:
- * <warning>This function may run the garbage collector.</warning>
- * All memory allocated with this function must be released with 
- * swfdec_as_context_unuse_mem(), when it is freed.
+ * in use, this function may decide to stop the script engine with an out of 
+ * memory error.
  *
  * Returns: %TRUE if the memory could be allocated. %FALSE on OOM.
  **/
@@ -105,6 +164,7 @@ swfdec_as_context_use_mem (SwfdecAsConte
 
   context->memory += bytes;
   context->memory_since_gc += bytes;
+  /* FIXME: Don't foget to abort on OOM */
   return TRUE;
 }
 
@@ -184,6 +244,13 @@ swfdec_as_context_collect (SwfdecAsConte
   SWFDEC_INFO (">> done collecting garbage");
 }
 
+/**
+ * swfdec_as_object_mark:
+ * @object: a #SwfdecAsObject
+ *
+ * Mark @object as being in use. Calling this function is only valid during
+ * the marking phase of garbage collection.
+ **/
 void
 swfdec_as_object_mark (SwfdecAsObject *object)
 {
@@ -197,6 +264,13 @@ swfdec_as_object_mark (SwfdecAsObject *o
   klass->mark (object);
 }
 
+/**
+ * swfdec_as_string_mark:
+ * @string: a garbage-collected string
+ *
+ * Mark @string as being in use. Calling this function is only valid during
+ * the marking phase of garbage collection.
+ **/
 void
 swfdec_as_string_mark (const char *string)
 {
@@ -205,6 +279,14 @@ swfdec_as_string_mark (const char *strin
     *str = SWFDEC_AS_GC_MARK;
 }
 
+/**
+ * swfdec_as_value_mark:
+ * @value: a #SwfdecAsValue
+ *
+ * Mark @value as being in use. This is just a convenience function that calls
+ * the right marking function depending on the value's type. Calling this 
+ * function is only valid during the marking phase of garbage collection.
+ **/
 void
 swfdec_as_value_mark (SwfdecAsValue *value)
 {
@@ -745,27 +827,38 @@ finish:
  * during evaluation, the return value will be the undefined value.
  **/
 void
-swfdec_as_context_eval (SwfdecAsContext *cx, SwfdecAsObject *obj, const char
*str,
+swfdec_as_context_eval (SwfdecAsContext *context, SwfdecAsObject *obj, const
char *str,
     SwfdecAsValue *val)
 {
-  g_return_if_fail (SWFDEC_IS_AS_CONTEXT (cx));
+  g_return_if_fail (SWFDEC_IS_AS_CONTEXT (context));
   g_return_if_fail (obj == NULL || SWFDEC_IS_AS_OBJECT (obj));
   g_return_if_fail (str != NULL);
   g_return_if_fail (val != NULL);
 
-  swfdec_as_context_eval_internal (cx, obj, str, val, FALSE);
+  swfdec_as_context_eval_internal (context, obj, str, val, FALSE);
 }
 
+/**
+ * swfdec_as_context_eval_set:
+ * @context: a #SwfdecAsContext
+ * @obj: #SwfdecAsObject to use as source for evaluating or NULL for the 
+ *       default object.
+ * @str: The string to evaluate
+ * @val: the value to set the variable to
+ *
+ * Sets the variable referenced by @str to @val. If @str does not reference 
+ * a valid property, nothing happens.
+ **/
 void
-swfdec_as_context_eval_set (SwfdecAsContext *cx, SwfdecAsObject *obj, const
char *str,
+swfdec_as_context_eval_set (SwfdecAsContext *context, SwfdecAsObject *obj,
const char *str,
     const SwfdecAsValue *val)
 {
-  g_return_if_fail (SWFDEC_IS_AS_CONTEXT (cx));
+  g_return_if_fail (SWFDEC_IS_AS_CONTEXT (context));
   g_return_if_fail (obj == NULL || SWFDEC_IS_AS_OBJECT (obj));
   g_return_if_fail (str != NULL);
   g_return_if_fail (val != NULL);
 
-  swfdec_as_context_eval_internal (cx, obj, str, (SwfdecAsValue *) val, TRUE);
+  swfdec_as_context_eval_internal (context, obj, str, (SwfdecAsValue *) val,
TRUE);
 }
 
 /*** AS CODE ***/
diff-tree 677831ce294814177191a5950e5320efb73d6e3d (from
f810682741113c7fb94a6a830233ae0d02833c39)
Author: Benjamin Otte <otte at gnome.org>
Date:   Fri Jun 29 02:00:23 2007 +0200

    remove unused swfdec_as_context_abort_oom()

diff --git a/libswfdec/swfdec_as_context.h b/libswfdec/swfdec_as_context.h
index d9815e4..ae625a9 100644
--- a/libswfdec/swfdec_as_context.h
+++ b/libswfdec/swfdec_as_context.h
@@ -100,7 +100,6 @@ const char *	swfdec_as_context_get_strin
 const char *	swfdec_as_context_give_string	(SwfdecAsContext *	context,
 						 char *			string);
 
-#define swfdec_as_context_abort_oom(context) swfdec_as_context_abort (context,
"Out of memory")
 void		swfdec_as_context_abort		(SwfdecAsContext *	context,
 						 const char *		reason);
 
@@ -119,11 +118,11 @@ void		swfdec_as_context_return	(SwfdecAs
 void		swfdec_as_context_trace		(SwfdecAsContext *	context,
 						 const char *		string);
 
-void		swfdec_as_context_eval		(SwfdecAsContext *	cx,
+void		swfdec_as_context_eval		(SwfdecAsContext *	context,
 						 SwfdecAsObject *	obj,
 						 const char *		str,
 						 SwfdecAsValue *	val);
-void		swfdec_as_context_eval_set	(SwfdecAsContext *	cx,
+void		swfdec_as_context_eval_set	(SwfdecAsContext *	context,
 						 SwfdecAsObject *	obj,
 						 const char *		str,
 						 const SwfdecAsValue *	val);