Merge pull request #2716 from hamishwillee/incoming

Move a bunch of files around to restructure "guidelines" section

site/source/docs/coding/Garbage_Collection.rst

@@ -1,32 +0,0 @@
-.. _GC:
-
-================================
-Garbage Collection (wiki-import)
-================================
-.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon!
-
-Emscripten has support for a Boehm-like API for garbage collection in C/C++ programs. This is useful if your application uses the Boehm API or if you are compiling a language like Java into C/C++ with the goal of then translating it to JavaScript.
-
-API Changes From Boehm
-----------------------
-
-There is no way to run another thread that interrupts the program at intervals in order to GC. So you need to call ``GC_MAYBE_COLLECT`` at reasonable intervals, which will do a collection if enough allocations happened since the last one. If you compile to HTML, a timer will be spun for this automatically and you don't need to do anything.
-
-You can also call ``GC_FORCE_COLLECT`` which forces a collection. This is useful if there are times in your app when responsiveness is not important (for example, right before starting a new level in a game).
-
-Mechanism
----------
-
-Static allocations are scanned, but the C and JS stacks are not. We can add such scanning at the cost of runtime performance, however, you don't need stack scanning if you compile for browsers and call ``GC_MAYBE_COLLECT`` from a ``setInterval``, since the interval will run when there is no relevant C or JS stack to scan (as mentioned before, such a timer will be run for you automatically if you are compiling to HTML).
-
-Pitfalls
---------
-
-The main risk with the current implementation is that we do not force a collection directly from allocations. So if you allocate a lot in between collections, you can run out of memory. You can call ``GC_FORCE_COLLECT`` to prevent this in some cases if you know relevant parts in your code.
-
-Relevant Files
---------------
-
--  ``system/include/gc.h``
--  ``src/library_gc.js``
-

site/source/docs/index.rst

@@ -8,7 +8,7 @@ Documentation Home (under-construction)
    
 	introducing_emscripten/index
 	getting_started/index
-	coding/index
+	porting/index
 	optimizing/index
 	compiling/index
 	packaging/index

site/source/docs/porting/guidelines/Asm-pointer-casts.rst

@@ -1,3 +1,16 @@
+=======================================
+Function Pointer Issues (wiki-import)
+=======================================
+
+There are three general issues with function pointers:
+
+#. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a **.c** file to **.cpp** for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.)
+
+#. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JavaScript engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information.
+
+#. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``.
+
+
 .. _Asm-pointer-casts:
 
 ===============================

site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst

@@ -1,7 +1,7 @@
 .. _CodeGuidelinesAndLimitations:
 
 =========================================================
-Code Guidelines and Limitations (under-construction)
+Portability Guidelines (under-construction)
 =========================================================
 
 This article describes the types of code that are more difficult to compile, code which compiles but may run more slowly, and issues and limitations with specific APIs. Developers will find it useful for evaluating the effort to port and re-write code.
@@ -50,13 +50,3 @@ Networking
 -  Emscripten supports libc networking functions, but since JavaScript networking is asynchronous, you must limit yourself to asynchronous (nonblocking) operations.
 
 
-Function pointer issues
-=======================
-
-There are three general issues with function pointers:
-
-#. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a **.c** file to **.cpp** for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.)
-
-#. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JavaScript engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information.
-
-#. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``.

site/source/docs/porting/guidelines/index.rst

@@ -0,0 +1,19 @@
+.. _guidelines-index:
+
+=====================================================
+Code Portability and Limitations (under-construction) 
+=====================================================
+
+This section is for .....
+
+
+.. toctree::
+	:maxdepth: 1
+   
+	CodeGuidelinesAndLimitations
+	Asm-pointer-casts
+	Browser-limitations
+
+	
+	
+   

site/source/docs/porting/index.rst

@@ -1,8 +1,8 @@
 .. _integrating-porting-index:
 
-==================================================
-Integrating/Porting (under-construction) 
-==================================================
+================================
+Porting (under-construction) 
+================================
 
 This section is for articles explaining the integration points with Emscripten, and general coding guidelines to help you with porting.
 
@@ -11,15 +11,12 @@ This section is for articles explaining the integration points with Emscripten,
 .. toctree::
 	:maxdepth: 1
    
-	CodeGuidelinesAndLimitations
+	guidelines/index
 	Emscripten-browser-environment
 	connecting_cpp_and_javascript/index
 	multimedia_and_graphics/index	
-	Asm-pointer-casts
 	Synchronous-Virtual-XHR-Backed-File-System-Usage
 	debugging/index
-	Browser-limitations
-	Garbage_Collection
 	
 	
    

site/source/index.rst

@@ -33,7 +33,7 @@ News
 
 	docs/introducing_emscripten/index
 	docs/getting_started/index
-	docs/coding/index
+	docs/porting/index
 	docs/optimizing/index
 	docs/compiling/index
 	docs/packaging/index