Requirements

Prerequisite knowledge

This tutorial requires familiarity with the C++ programming language, as well as a working knowledge of the Adobe Flash C++ Compiler. Familiarity with concurrent programming techniques will also help you make the most of this article.

User level

Intermediate

The Adobe Flash C++ Compiler (FlasCC) has support for the POSIX threads (Pthreads) API when targeting Flash Player 11.5 and above with SWF version 18+. This API enables thread creation and management as well as interthread synchronization via mutex and condition primitives. This article provides an overview of Pthreads and related technologies such as semaphores, atomic operations, and OpenMP in the context of the Flash runtimes.  You can download and explore the sample files for this article to see how these technologies can be implemented in C++.

Pthreads

The Pthreads API enables use of concurrent programming techniques and multiple CPU cores through the ability to create multiple threads of execution in a single application. In a C or C++ program, inclusion of the pthread.h header provides definitions for Pthread data structures and functions. The –pthread gcc compiler option ensures all required libraries will be linked into the final application.

Thread lifetimes

New threads of execution are created with the pthread_create function. Threads must be joined when they are finished to prevent resource leaks. Threads are joined using the pthread_join function.

Synchronization primitives

The sample files for this article include pthreads.cpp, which demonstrates thread creation and joining as well as various Pthread synchronization primitives to implement a blocking fixed-capacity queue. This example uses mutexes created by pthread_mutex_init and conditions created by pthread_cond_init.

Semaphores and Atomic Operations

Flascc supports counting semaphores through the sem_ family of data structures and functions defined by the semaphore.h header. Semaphores are typically used to arbitrate access by an unlimited number of threads to a limited number of resources.

Flascc also supports the __sync_ family of atomic operations. These atomic operations enable synchronous manipulation of integer and pointer values, including synchronous integer increment and compare-and-swap of integers and pointers among others. With these primitive operations, you can implement a variety of lock-free algorithms.

Semaphores

The sema.cpp sample file demonstrates the use of semaphores created with sem_init to implement a blocking fixed-capacity queue. In this example, the limited resource is the number of available slots in the queue.

Atomic operations

The atomic.cpp sample file demonstrates the use of __sync_ primitives to implement a lock-free linked list add operation. For more information on supported atomic operations, see this page.

OpenMP

OpenMP is a set of APIs and compiler directives that enables parallel programming without explicit thread management or synchronization. In a C or C++ program, inclusion of the omp.h header provides definitions of OpenMP related data structures and functions. However, in many cases, the OpenMP API need not be called directly as the compiler directives are often sufficient by themselves. The –fopenmp compiler option ensures that the compiler will honor the OpenMP compiler directives and link in required libraries. The option must be accompanied by the –pthread option.

Visit http://openmp.org for more information on OpenMP, including tutorials and a helpful syntax quick reference card.

Sample

The openmp.cpp sample file demonstrates use of the omp parallel for compiler directive  to perform some simple parallel computation.  See "Parallel Loop [2.6.1]" in the OpenMP specification or on the syntax quick reference card for more details on this directive.

Threads and Workers

Flascc Pthreads are implemented using ActionScript workers. Creation of a Pthread causes the creation of an AS3 Worker object on which the Pthread start_routine runs. Workers created for Pthread execution automatically share C memory with other Pthreads including the main Pthread. Global and static variables are shared between Pthreads. Therefore, C data—including pointers to scalars, function pointers, and so on—can be safely shared between Pthreads. However, AS3 values are not shared between workers and therefore are not generally shareable between Pthreads. The workers.cpp sample file demonstrates the relationship between workers and Pthreads.

This relationship is especially important to consider when using SWIG (see "Creating SWCs with SWIG" in the flascc Reference Guide, docs/Reference.html, in your flascc installation). SWIG is capable of dynamically creating C function pointers from AS3 functions and vice versa. These SWIG-created function pointers may not be shared across workers as they encapsulate AS3 Functions. This means that they should not be shared across Pthreads.

UI worker

In a Pthread enabled application built using Flascc, the main entry point runs in a background worker to prevent timeouts due to main executing for an extended period of time. The primordial or "UI" worker periodically services requests made when other threads make I/O requests, use Flash++, or call avm2_ui_thunk (see docs/capidocs/avm2.html in your flascc installation). The requests are executed by impersonating the requesting threads. Additionally, with a custom Console (see "Implementing a Console" in the flascc Reference Guide, docs/Reference.html, in your flascc installation), the UI worker can execute C code under other circumstances. This code will behave as if run from a Pthread that is distinct from the main Pthread and any other explicitly created Pthreads. The UI worker, like the main thread and explicitly created Pthreads, has its own thread local storage accessible via pthread_getspecific/pthread_setspecific as well as a unique pthread_t as returned by pthread_self.

Flash++

Flascc provides C++ wrapper classes for the Flash API. Including Flash++.h and linking with the appropriate libraries by passing –lFlash++ and –lAS3++ to the compiler enables use of these wrapper classes.

Each wrapper class comes in two variants. The first variant is the "local" variant in namespace AS3::local. These classes operate on AS3 values in the context of the executing worker. This means that access to mouse or keyboard input, the Clipboard, and so on will not work outside of the primordial/UI worker. Cross-worker sharing of these types will result in (hard to debug!) runtime errors. This means that they should not be shared across Pthreads.

The second variant is the "ui" variant in namespace AS3::ui. These classes operate on AS3 values that are maintained in the primordial/UI Worker. As accesses to these types are automatically delegated to the primordial/UI Worker, they may be shared across workers/Pthreads and may be used to access UI features from any worker/Pthread. There is some performance overhead associated with this delegation, and these types should be used with caution when performance is a priority.

The flash++flavors.cpp sample file demonstrates the differences between the two variants of Flash++ classes and how they interact with Pthreads and workers. The flash++ui.cpp sample file demonstrates use of the "ui" variant of Flash++ to interact with the Flash API from multiple threads.

Where to go from here

Flascc support for threading enables developers to use powerful concurrent programming techniques to take advantage of modern multicore CPUs while reaching the vast Flash Runtime audience. Be sure to check out the extensive documentation and samples around threads and other topics in the Adobe Flash C++ Compiler SDK.