Merge branch 'true-async-api' into true-async

Author: EdmondDantes

Zend/zend_async_API.c

@@ -48,13 +48,31 @@ static void shutdown_stub(void) {}
 
 static zend_array* get_coroutines_stub(void) { return NULL; }
 
-static zend_future_t* future_create_stub(bool thread_safe, size_t extra_size) 
+static zend_future_t* new_future_stub(bool thread_safe, size_t extra_size) 
 {
 	ASYNC_THROW_ERROR("Async API is not enabled");
 	return NULL;
 }
 
-static zend_async_channel_t* channel_create_stub(size_t buffer_size, bool resizable, bool thread_safe, size_t extra_size) 
+static zend_async_channel_t* new_channel_stub(size_t buffer_size, bool resizable, bool thread_safe, size_t extra_size) 
+{
+	ASYNC_THROW_ERROR("Async API is not enabled");
+	return NULL;
+}
+
+static zend_async_group_t* new_group_stub(size_t extra_size) 
+{
+	ASYNC_THROW_ERROR("Async API is not enabled");
+	return NULL;
+}
+
+static zend_object* new_future_obj_stub(zend_future_t *future) 
+{
+	ASYNC_THROW_ERROR("Async API is not enabled");
+	return NULL;
+}
+
+static zend_object* new_channel_obj_stub(zend_async_channel_t *channel) 
 {
 	ASYNC_THROW_ERROR("Async API is not enabled");
 	return NULL;
@@ -109,8 +127,13 @@ zend_async_get_coroutines_t zend_async_get_coroutines_fn = get_coroutines_stub;
 zend_async_add_microtask_t zend_async_add_microtask_fn = add_microtask_stub;
 zend_async_get_awaiting_info_t zend_async_get_awaiting_info_fn = get_awaiting_info_stub;
 zend_async_get_class_ce_t zend_async_get_class_ce_fn = get_class_ce;
-zend_async_future_create_t zend_async_future_create_fn = future_create_stub;
-zend_async_channel_create_t zend_async_channel_create_fn = channel_create_stub;
+zend_async_new_future_t zend_async_new_future_fn = new_future_stub;
+zend_async_new_channel_t zend_async_new_channel_fn = new_channel_stub;
+zend_async_new_future_obj_t zend_async_new_future_obj_fn = new_future_obj_stub;
+zend_async_new_channel_obj_t zend_async_new_channel_obj_fn = new_channel_obj_stub;
+
+/* GROUP API */
+zend_async_new_group_t zend_async_new_group_fn = new_group_stub;
 
 static zend_atomic_bool reactor_lock = {0};
 static char * reactor_module_name = NULL;
@@ -243,6 +266,11 @@ ZEND_API bool zend_async_scheduler_register(
     zend_async_get_awaiting_info_t get_awaiting_info_fn,
     zend_async_get_class_ce_t get_class_ce_fn,
     zend_async_new_iterator_t new_iterator_fn,
+    zend_async_new_future_t new_future_fn,
+    zend_async_new_channel_t new_channel_fn,
+    zend_async_new_future_obj_t new_future_obj_fn,
+    zend_async_new_channel_obj_t new_channel_obj_fn,
+    zend_async_new_group_t new_group_fn,
     zend_async_engine_shutdown_t engine_shutdown_fn
 )
 {
@@ -280,6 +308,11 @@ ZEND_API bool zend_async_scheduler_register(
 	zend_async_get_awaiting_info_fn = get_awaiting_info_fn;
 	zend_async_get_class_ce_fn = get_class_ce_fn;
 	zend_async_new_iterator_fn = new_iterator_fn;
+	zend_async_new_future_fn = new_future_fn;
+	zend_async_new_channel_fn = new_channel_fn;
+	zend_async_new_future_obj_fn = new_future_obj_fn;
+	zend_async_new_channel_obj_fn = new_channel_obj_fn;
+	zend_async_new_group_fn = new_group_fn;
     zend_async_engine_shutdown_fn = engine_shutdown_fn;
 
 	zend_atomic_bool_store(&scheduler_lock, 0);

Zend/zend_async_API.h

@@ -19,9 +19,9 @@
 #include "zend_fibers.h"
 #include "zend_globals.h"
 
-#define ZEND_ASYNC_API "TrueAsync API v0.4.0"
+#define ZEND_ASYNC_API "TrueAsync API v0.5.0"
 #define ZEND_ASYNC_API_VERSION_MAJOR 0
-#define ZEND_ASYNC_API_VERSION_MINOR 4
+#define ZEND_ASYNC_API_VERSION_MINOR 5
 #define ZEND_ASYNC_API_VERSION_PATCH 0
 
 #define ZEND_ASYNC_API_VERSION_NUMBER \
@@ -106,6 +106,7 @@ typedef enum
 
 	ZEND_ASYNC_CLASS_CHANNEL = 10,
 	ZEND_ASYNC_CLASS_FUTURE = 11,
+	ZEND_ASYNC_CLASS_GROUP = 12,
 
 	ZEND_ASYNC_EXCEPTION_DEFAULT = 30,
 	ZEND_ASYNC_EXCEPTION_CANCELLATION = 31,
@@ -134,6 +135,7 @@ typedef struct _zend_async_waker_s zend_async_waker_t;
 typedef struct _zend_async_microtask_s zend_async_microtask_t;
 typedef struct _zend_async_scope_s zend_async_scope_t;
 typedef struct _zend_async_iterator_s zend_async_iterator_t;
+typedef struct _zend_async_group_s zend_async_group_t;
 typedef struct _zend_fcall_s zend_fcall_t;
 typedef void (*zend_coroutine_entry_t)(void);
 
@@ -217,8 +219,13 @@ typedef zend_array* (*zend_async_get_coroutines_t)(void);
 typedef void (*zend_async_add_microtask_t)(zend_async_microtask_t *microtask);
 typedef zend_array* (*zend_async_get_awaiting_info_t)(zend_coroutine_t * coroutine);
 typedef zend_class_entry* (*zend_async_get_class_ce_t)(zend_async_class type);
-typedef zend_future_t* (*zend_async_future_create_t)(bool thread_safe, size_t extra_size);
-typedef zend_async_channel_t* (*zend_async_channel_create_t)(size_t buffer_size, bool resizable, bool thread_safe, size_t extra_size);
+typedef zend_future_t* (*zend_async_new_future_t)(bool thread_safe, size_t extra_size);
+typedef zend_async_channel_t* (*zend_async_new_channel_t)(size_t buffer_size, bool resizable, bool thread_safe, size_t extra_size);
+
+typedef zend_async_group_t* (*zend_async_new_group_t)(size_t extra_size);
+
+typedef zend_object* (*zend_async_new_future_obj_t)(zend_future_t *future);
+typedef zend_object* (*zend_async_new_channel_obj_t)(zend_async_channel_t *channel);
 
 typedef void (*zend_async_reactor_startup_t)(void);
 typedef void (*zend_async_reactor_shutdown_t)(void);
@@ -286,6 +293,8 @@ typedef int (* zend_async_exec_t) (
 
 typedef void (*zend_async_queue_task_t)(zend_async_task_t *task);
 
+typedef void (*zend_async_task_run_t)(zend_async_task_t *task);
+
 typedef void (*zend_async_microtask_handler_t)(zend_async_microtask_t *microtask);
 
 struct _zend_fcall_s {
@@ -732,6 +741,7 @@ struct _zend_async_listen_event_s {
 
 struct _zend_async_task_s {
 	zend_async_event_t base;
+	zend_async_task_run_t run;
 };
 
 struct _zend_async_trigger_event_s {
@@ -1259,8 +1269,13 @@ ZEND_API extern zend_async_get_coroutines_t zend_async_get_coroutines_fn;
 ZEND_API extern zend_async_add_microtask_t zend_async_add_microtask_fn;
 ZEND_API extern zend_async_get_awaiting_info_t zend_async_get_awaiting_info_fn;
 ZEND_API extern zend_async_get_class_ce_t zend_async_get_class_ce_fn;
-ZEND_API extern zend_async_future_create_t zend_async_future_create_fn;
-ZEND_API extern zend_async_channel_create_t zend_async_channel_create_fn;
+ZEND_API extern zend_async_new_future_t zend_async_new_future_fn;
+ZEND_API extern zend_async_new_channel_t zend_async_new_channel_fn;
+ZEND_API extern zend_async_new_future_obj_t zend_async_new_future_obj_fn;
+ZEND_API extern zend_async_new_channel_obj_t zend_async_new_channel_obj_fn;
+
+/* GROUP API */
+ZEND_API extern zend_async_new_group_t zend_async_new_group_fn;
 
 /* Iterator API */
 ZEND_API extern zend_async_new_iterator_t zend_async_new_iterator_fn;
@@ -1335,6 +1350,11 @@ ZEND_API bool zend_async_scheduler_register(
     zend_async_get_awaiting_info_t get_awaiting_info_fn,
     zend_async_get_class_ce_t get_class_ce_fn,
     zend_async_new_iterator_t new_iterator_fn,
+    zend_async_new_future_t new_future_fn,
+    zend_async_new_channel_t new_channel_fn,
+    zend_async_new_future_obj_t new_future_obj_fn,
+    zend_async_new_channel_obj_t new_channel_obj_fn,
+    zend_async_new_group_t new_group_fn,
     zend_async_engine_shutdown_t engine_shutdown_fn
 );
 
@@ -1446,12 +1466,18 @@ ZEND_API void zend_async_add_main_coroutine_start_handler(
 ZEND_API void zend_async_call_main_coroutine_start_handlers(zend_coroutine_t *main_coroutine);
 
 /* Future API Functions */
-#define ZEND_ASYNC_NEW_FUTURE(thread_safe) zend_async_future_create_fn(thread_safe, 0)
-#define ZEND_ASYNC_NEW_FUTURE_EX(thread_safe, extra_size) zend_async_future_create_fn(thread_safe, extra_size)
+#define ZEND_ASYNC_NEW_FUTURE(thread_safe) zend_async_new_future_fn(thread_safe, 0)
+#define ZEND_ASYNC_NEW_FUTURE_EX(thread_safe, extra_size) zend_async_new_future_fn(thread_safe, extra_size)
+#define ZEND_ASYNC_NEW_FUTURE_OBJ(future) zend_async_new_future_obj_fn(future)
 
 /* Channel API Functions */
-#define ZEND_ASYNC_NEW_CHANNEL(buffer_size, resizable, thread_safe) zend_async_channel_create_fn(buffer_size, resizable, thread_safe, 0)
-#define ZEND_ASYNC_NEW_CHANNEL_EX(buffer_size, resizable, thread_safe, extra_size) zend_async_channel_create_fn(buffer_size, resizable, thread_safe, extra_size)
+#define ZEND_ASYNC_NEW_CHANNEL(buffer_size, resizable, thread_safe) zend_async_new_channel_fn(buffer_size, resizable, thread_safe, 0)
+#define ZEND_ASYNC_NEW_CHANNEL_EX(buffer_size, resizable, thread_safe, extra_size) zend_async_new_channel_fn(buffer_size, resizable, thread_safe, extra_size)
+#define ZEND_ASYNC_NEW_CHANNEL_OBJ(channel) zend_async_new_channel_obj_fn(channel)
+
+/* GROUP API Functions */
+#define ZEND_ASYNC_NEW_GROUP() zend_async_new_group_fn(0)
+#define ZEND_ASYNC_NEW_GROUP_EX(extra_size) zend_async_new_group_fn(extra_size)
 
 END_EXTERN_C()
 

docs/source/miscellaneous/writing-tests.rst

@@ -95,13 +95,13 @@ might use a variation tests to test boundary conditions.
 How big is a test case?
 =======================
 
-Small. Really — the smaller the better, a good guide is no more than 10 lines of output. The reason
-for this is that if we break something in PHP and it breaks your test case we need to be able to
-find out quite quickly what we broke, going through 1000s of line of test case output is not easy.
-Having said that it's sometimes just not practical to stay within the 10 line guideline, in this
-case you can help a lot by commenting the output. You may find plenty of much longer tests in PHP -
-the small tests message is something that we learnt over time, in fact we are slowly going through
-and splitting tests up when we need to.
+Small. Really — the smaller the better, a good guide is no more than 10 lines of output. The
+reason for this is that if we break something in PHP and it breaks your test case we need to be able
+to find out quite quickly what we broke, going through 1000s of line of test case output is not
+easy. Having said that it's sometimes just not practical to stay within the 10 line guideline, in
+this case you can help a lot by commenting the output. You may find plenty of much longer tests in
+PHP - the small tests message is something that we learnt over time, in fact we are slowly going
+through and splitting tests up when we need to.
 
 Comments
 ========
@@ -183,10 +183,10 @@ Testing your test cases
 
 Most people who write tests for PHP don't have access to a huge number of operating systems but the
 tests are run on every system that runs PHP. It's good to test your test on as many platforms as you
-can — Linux and Windows are the most important, it's increasingly important to make sure that tests
-run on 64 bit as well as 32 bit platforms. If you only have access to one operating system — don't
-worry, if you have karma, commit the test but watch php-qa@lists.php.net for reports of failures on
-other platforms. If you don't have karma to commit have a look at the next section.
+can — Linux and Windows are the most important, it's increasingly important to make sure that
+tests run on 64 bit as well as 32 bit platforms. If you only have access to one operating system —
+don't worry, if you have karma, commit the test but watch php-qa@lists.php.net for reports of
+failures on other platforms. If you don't have karma to commit have a look at the next section.
 
 When you are testing your test case it's really important to make sure that you clean up any
 temporary resources (eg files) that you used in the test. There is a special ``--CLEAN--`` section