Parallel conference bridge (#4241)

Author: LeonidGoltsblat

pjmedia/build/Makefile

@@ -59,7 +59,7 @@ export _LDFLAGS := $(APP_THIRD_PARTY_LIBS) \
 export PJMEDIA_SRCDIR = ../src/pjmedia
 export PJMEDIA_OBJS += $(OS_OBJS) $(M_OBJS) $(CC_OBJS) $(HOST_OBJS) \
 			alaw_ulaw.o alaw_ulaw_table.o avi_player.o avi_writer.o av_sync.o \
-			bidirectional.o clock_thread.o codec.o conference.o \
+			bidirectional.o clock_thread.o codec.o conference.o conf_thread.o \
 			conf_switch.o converter.o  converter_libswscale.o converter_libyuv.o \
 			delaybuf.o echo_common.o \
 			echo_port.o echo_suppress.o echo_webrtc.o echo_webrtc_aec3.o \

pjmedia/build/pjmedia.vcxproj

@@ -616,6 +616,7 @@
     <ClCompile Include="..\src\pjmedia\clock_thread.c" />
     <ClCompile Include="..\src\pjmedia\codec.c" />
     <ClCompile Include="..\src\pjmedia\conference.c" />
+    <ClCompile Include="..\src\pjmedia\conf_thread.c" />
     <ClCompile Include="..\src\pjmedia\conf_switch.c" />
     <ClCompile Include="..\src\pjmedia\converter.c" />
     <ClCompile Include="..\src\pjmedia\converter_libswscale.c" />

pjmedia/build/pjmedia.vcxproj.filters

@@ -38,6 +38,9 @@
     <ClCompile Include="..\src\pjmedia\conference.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\src\pjmedia\conf_thread.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="..\src\pjmedia\converter.c">
       <Filter>Source Files</Filter>
     </ClCompile>
@@ -239,6 +242,9 @@
     <ClCompile Include="..\src\pjmedia\av_sync.c">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="..\src\pjmedia\stream_imp_common.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="..\include\pjmedia\alaw_ulaw.h">

pjmedia/include/pjmedia/conference.h

@@ -208,6 +208,96 @@ enum pjmedia_conf_option
                                      based.                                 */
 };
 
+/**
+ * This structure specifies the conference bridge creation parameters.
+ */
+typedef struct pjmedia_conf_param
+{
+    /**
+     * Maximum number of slots/ports to be created in
+     * the bridge. Note that the bridge internally uses
+     * one port for the sound device, so the actual 
+     * maximum number of ports will be less one than
+     * this value.
+     */
+    unsigned max_slots;
+
+    /**
+     * Set the sampling rate of the bridge. This value
+     * is also used to set the sampling rate of the
+     * sound device.
+     */
+    unsigned sampling_rate;
+
+    /**
+     * Number of channels in the PCM stream. Normally
+     * the value will be 1 for mono, but application may
+     * specify a value of 2 for stereo. Note that all
+     * ports that will be connected to the bridge MUST 
+     * have the same number of channels as the bridge.
+     */
+    unsigned channel_count;
+
+    /**
+     * Set the number of samples per frame. This value
+     * is also used to set the sound device.
+     */
+    unsigned samples_per_frame;
+
+    /**
+     * Set the number of bits per sample. This value
+     * is also used to set the sound device. Currently
+     * only 16bit per sample is supported.
+     */
+    unsigned bits_per_sample;
+
+    /**
+     * Bitmask options to be set for the bridge. The
+     * options are constructed from #pjmedia_conf_option
+     * enumeration.
+     * The default value is zero.
+     */
+    unsigned options;
+
+    /** 
+     * The number of worker threads to use by conference bridge.
+     * Zero means the operations will be done only by get_frame() thread, 
+     * i.e. conference bridge will be sequential.
+     * Set this parameter to non-zero value to enable parallel processing.
+     * The number of worker threads should be less than or equal to the number 
+     * of the processor cores. However, the optimal number of worker threads
+     * is application and hardware dependent.
+     * The default value is zero - sequential conference bridge.
+     * This value is compatible with previous behavior.
+     * At compile time application developer can change the default value by 
+     * setting #PJMEDIA_CONF_THREADS macro in the config_site.h.
+     * PJMEDIA_CONF_THREADS is total number of conference bridge threads 
+     * including get_frame() thread. worker_threads is the number of conference
+     * bridge threads excluding get_frame() thread. 
+     * As a general rule worker_threads is 1 less than PJMEDIA_CONF_THREADS.
+     * This value is ignored by all conference backends except for the 
+     * multithreaded conference bridge backend
+     * (PJMEDIA_CONF_PARALLEL_BRIDGE_BACKEND).
+     * 
+     * The total number of conference bridge threads can be configured at the
+     * pjsua level using the pjsua_media_config::conf_threads parameter, or at
+     * the pjsua2 level using the pjsua2::MediaConfig::confThreads parameter.
+     */
+    unsigned worker_threads;
+} pjmedia_conf_param;
+
+
+/**
+ * Initialize conference bridge creation parameters.
+ */
+PJ_INLINE(void) pjmedia_conf_param_default(pjmedia_conf_param *param)
+{
+    pj_bzero(param, sizeof(pjmedia_conf_param));
+    /* Set the default values */
+#if defined(PJMEDIA_CONF_THREADS) && PJMEDIA_CONF_THREADS > 1
+    param->worker_threads = PJMEDIA_CONF_THREADS-1;
+#endif
+}
 
 /**
  * Create conference bridge with the specified parameters. The sampling rate,
@@ -274,6 +364,47 @@ PJ_DECL(pj_status_t) pjmedia_conf_create( pj_pool_t *pool,
                                           unsigned options,
                                           pjmedia_conf **p_conf );
 
+/**
+ * Create conference bridge with the specified parameters. The sampling rate,
+ * samples per frame, and bits per sample will be used for the internal
+ * operation of the bridge (e.g. when mixing audio frames). However, ports
+ * with different configuration may be connected to the bridge. In this case,
+ * the bridge is able to perform sampling rate conversion, and buffering in
+ * case the samples per frame is different.
+ *
+ * For this version of PJMEDIA, only 16bits per sample is supported.
+ *
+ * For this version of PJMEDIA, the channel count of the ports MUST match
+ * the channel count of the bridge.
+ *
+ * Under normal operation (i.e. when PJMEDIA_CONF_NO_DEVICE option is NOT
+ * specified), the bridge internally create an instance of sound device
+ * and connect the sound device to port zero of the bridge.
+ *
+ * If PJMEDIA_CONF_NO_DEVICE options is specified, no sound device will
+ * be created in the conference bridge. Application MUST acquire the port
+ * interface of the bridge by calling #pjmedia_conf_get_master_port(), and
+ * connect this port interface to a sound device port by calling
+ * #pjmedia_snd_port_connect(), or to a master port (pjmedia_master_port)
+ * if application doesn't want to instantiate any sound devices.
+ *
+ * The sound device or master port are crucial for the bridge's operation,
+ * because it provides the bridge with necessary clock to process the audio
+ * frames periodically. Internally, the bridge runs when get_frame() to
+ * port zero is called.
+ *
+ * @param pool              Pool to use to allocate the bridge and
+ *                          additional buffers for the sound device.
+ * @param param             The conference bridge creation parameters.
+ *                          See #pjmedia_conf_param for more information.
+ * @param p_conf            Pointer to receive the conference bridge instance.
+ *
+ * @return                  PJ_SUCCESS if conference bridge can be created.
+ */
+PJ_DECL(pj_status_t) pjmedia_conf_create2(pj_pool_t *pool,
+                                          pjmedia_conf_param *param,
+                                          pjmedia_conf **p_conf);
+
 
 /**
  * Destroy conference bridge. This will also remove any port, thus application

pjmedia/include/pjmedia/config.h

@@ -120,6 +120,64 @@
 #   define PJMEDIA_CONF_USE_AGC             1
 #endif
 
+/**
+ * Conference switch/bridge backend implementations.
+ * Select one of these implementations in PJMEDIA_CONF_BACKEND.
+ */
+/** Conference switch board backend */
+#define PJMEDIA_CONF_SWITCH_BOARD_BACKEND 0
+/** Conference bridge sequential backend */
+#define PJMEDIA_CONF_SERIAL_BRIDGE_BACKEND 1
+/** Multithreaded conference bridge backend */
+#define PJMEDIA_CONF_PARALLEL_BRIDGE_BACKEND 2
+
+/**
+ * Choose which conference backend implementation to use.
+ * 
+ * In order to use parallel conference bridge with real parallelism,
+ * users need to:
+ * 1. define PJMEDIA_CONF_BACKEND to PJMEDIA_CONF_PARALLEL_BRIDGE_BACKEND
+ * and at least one of the following:
+ * 2.1. define PJMEDIA_CONF_THREADS with a value > 1
+ *   This option allows pjmedia_conf_create() to create a parallel conference
+ *   and so convert any existing serial conference to parallel conference 
+ *   without changing the code.
+ * OR
+ * 2.2. use pjmedia_conf_create2() with pjmedia_conf_param::worker_threads
+ * initialized to a value > 0.
+ *
+ * Default is PJMEDIA_CONF_SERIAL_BRIDGE_BACKEND, 
+ * however 
+ * if PJMEDIA_CONF_USE_SWITCH_BOARD macro was defined, project system
+ *   selects PJMEDIA_CONF_SWITCH_BOARD_BACKEND by default,
+ * otherwise if PJMEDIA_CONF_THREADS macro was defined, project system 
+ *   selects PJMEDIA_CONF_PARALLEL_BRIDGE_BACKEND by default.
+ */
+#ifndef PJMEDIA_CONF_BACKEND
+#   if defined(PJMEDIA_CONF_USE_SWITCH_BOARD) && PJMEDIA_CONF_USE_SWITCH_BOARD!=0
+#       define PJMEDIA_CONF_BACKEND PJMEDIA_CONF_SWITCH_BOARD_BACKEND
+#   elif defined(PJMEDIA_CONF_THREADS)
+#       define PJMEDIA_CONF_BACKEND PJMEDIA_CONF_PARALLEL_BRIDGE_BACKEND
+#   else
+#       define PJMEDIA_CONF_BACKEND PJMEDIA_CONF_SERIAL_BRIDGE_BACKEND
+#   endif 
+#endif  //PJMEDIA_CONF_BACKEND
+
+ /**
+ * The default value for the total number of threads, including get_frame()
+ * thread, that can be used by the conference bridge.
+ * This value is used to determine if the conference bridge should be
+ * implemented as a parallel bridge or not.
+ * If this value is set to 1, the conference bridge will be implemented as a
+ * serial bridge, otherwise it will be implemented as a parallel bridge.
+ * PJMEDIA_CONF_THREADS should not be less than 1.
+ *
+ * Default value: 1 - serial bridge
+ */
+#ifndef PJMEDIA_CONF_THREADS
+#   define PJMEDIA_CONF_THREADS  1
+#endif
+
 
 /*
  * Types of sound stream backends.

pjmedia/src/pjmedia/conf_switch.c

@@ -29,7 +29,7 @@
 #include <pj/pool.h>
 #include <pj/string.h>
 
-#if defined(PJMEDIA_CONF_USE_SWITCH_BOARD) && PJMEDIA_CONF_USE_SWITCH_BOARD!=0
+#if PJMEDIA_CONF_BACKEND == PJMEDIA_CONF_SWITCH_BOARD_BACKEND
 
 /* CONF_DEBUG enables detailed operation of the conference bridge.
  * Beware that it prints large amounts of logs (several lines per frame).
@@ -209,6 +209,16 @@ static pj_status_t create_sound_port( pj_pool_t *pool,
     return PJ_SUCCESS;
 }
 
+PJ_DEF(pj_status_t) pjmedia_conf_create2(pj_pool_t *pool,
+                                         pjmedia_conf_param *param,
+                                         pjmedia_conf **p_conf)
+{
+    return pjmedia_conf_create(pool,
+                               param.max_slots, param.sampling_rate,
+                               param.channel_count, param.samples_per_frame,
+                               param.bits_per_sample, param.options, p_conf);
+}
+
 /*
  * Create conference bridge.
  */
@@ -1636,4 +1646,4 @@ PJ_DEF(pj_status_t) pjmedia_conf_del_destroy_handler(
 }
 
 
-#endif
+#endif /* PJMEDIA_CONF_BACKEND == PJMEDIA_CONF_SWITCH_BOARD_BACKEND */