Add zend_observer API

Closes GH-5857.

Co-authored-by: Nikita Popov <nikita.ppv@gmail.com>
Co-authored-by: Sammy Powers <sammyk@datadoghq.com>

Zend/zend.c

@@ -33,6 +33,7 @@
 #include "zend_smart_string.h"
 #include "zend_cpuinfo.h"
 #include "zend_attributes.h"
+#include "zend_observer.h"
 
 static size_t global_map_ptr_last = 0;
 
@@ -1205,6 +1206,7 @@ ZEND_API void zend_activate(void) /* {{{ */
 	if (CG(map_ptr_last)) {
 		memset(ZEND_MAP_PTR_REAL_BASE(CG(map_ptr_base)), 0, CG(map_ptr_last) * sizeof(void*));
 	}
+	zend_observer_activate();
 }
 /* }}} */
 
@@ -1221,6 +1223,8 @@ ZEND_API void zend_deactivate(void) /* {{{ */
 	/* we're no longer executing anything */
 	EG(current_execute_data) = NULL;
 
+	zend_observer_deactivate();
+
 	zend_try {
 		shutdown_scanner();
 	} zend_end_try();

Zend/zend_execute.c

@@ -40,6 +40,7 @@
 #include "zend_inheritance.h"
 #include "zend_type_info.h"
 #include "zend_smart_str.h"
+#include "zend_observer.h"
 
 /* Virtual current working directory support */
 #include "zend_virtual_cwd.h"

Zend/zend_execute_API.c

@@ -35,6 +35,7 @@
 #include "zend_float.h"
 #include "zend_weakrefs.h"
 #include "zend_inheritance.h"
+#include "zend_observer.h"
 #ifdef HAVE_SYS_TIME_H
 #include <sys/time.h>
 #endif
@@ -869,6 +870,9 @@ zend_result zend_call_function(zend_fcall_info *fci, zend_fcall_info_cache *fci_
 		uint32_t orig_jit_trace_num = EG(jit_trace_num);
 
 		zend_init_func_execute_data(call, &func->op_array, fci->retval);
+		if (ZEND_OBSERVER_ENABLED) {
+			zend_observer_maybe_fcall_call_begin(call);
+		}
 		zend_execute_ex(call);
 		EG(jit_trace_num) = orig_jit_trace_num;
 		EG(opline_before_exception) = current_opline_before_exception;

Zend/zend_generators.c

@@ -24,6 +24,7 @@
 #include "zend_generators.h"
 #include "zend_closures.h"
 #include "zend_generators_arginfo.h"
+#include "zend_observer.h"
 
 ZEND_API zend_class_entry *zend_ce_generator;
 ZEND_API zend_class_entry *zend_ce_ClosedGeneratorException;
@@ -774,7 +775,25 @@ ZEND_API void zend_generator_resume(zend_generator *orig_generator) /* {{{ */
 
 		/* Resume execution */
 		generator->flags |= ZEND_GENERATOR_CURRENTLY_RUNNING;
-		zend_execute_ex(generator->execute_data);
+		if (!ZEND_OBSERVER_ENABLED) {
+			zend_execute_ex(generator->execute_data);
+		} else {
+			zend_op_array *op_array = &generator->execute_data->func->op_array;
+			void *observer_handlers = ZEND_OBSERVER_HANDLERS(op_array);
+			if (!observer_handlers) {
+				zend_observer_fcall_install((zend_function *)op_array);
+				observer_handlers = ZEND_OBSERVER_HANDLERS(op_array);
+			}
+			ZEND_ASSERT(observer_handlers);
+			if (observer_handlers != ZEND_OBSERVER_NOT_OBSERVED) {
+				zend_observe_fcall_begin(observer_handlers, generator->execute_data);
+			}
+			zend_execute_ex(generator->execute_data);
+			if (generator->execute_data) {
+				/* On the final return, this will be called from ZEND_GENERATOR_RETURN */
+				zend_observer_maybe_fcall_call_end(generator->execute_data, &generator->value);
+			}
+		}
 		generator->flags &= ~ZEND_GENERATOR_CURRENTLY_RUNNING;
 
 		generator->frozen_call_stack = NULL;

Zend/zend_observer.c

@@ -0,0 +1,160 @@
+/*
+   +----------------------------------------------------------------------+
+   | Zend Engine                                                          |
+   +----------------------------------------------------------------------+
+   | Copyright (c) Zend Technologies Ltd. (http://www.zend.com)           |
+   +----------------------------------------------------------------------+
+   | This source file is subject to version 2.00 of the Zend license,     |
+   | that is bundled with this package in the file LICENSE, and is        |
+   | available through the world-wide-web at the following url:           |
+   | http://www.zend.com/license/2_00.txt.                                |
+   | If you did not receive a copy of the Zend license and are unable to  |
+   | obtain it through the world-wide-web, please send a note to          |
+   | license@zend.com so we can mail you a copy immediately.              |
+   +----------------------------------------------------------------------+
+   | Authors: Levi Morrison <levim@php.net>                               |
+   |          Sammy Kaye Powers <sammyk@php.net>                          |
+   +----------------------------------------------------------------------+
+*/
+
+#include "zend_observer.h"
+
+#include "zend_extensions.h"
+#include "zend_llist.h"
+#include "zend_vm.h"
+
+zend_llist zend_observers_fcall_list;
+int zend_observer_fcall_op_array_extension = -1;
+
+ZEND_TLS zend_arena *fcall_handlers_arena = NULL;
+
+ZEND_API extern inline void zend_observer_maybe_fcall_call_begin(
+	zend_execute_data *execute_data);
+ZEND_API extern inline void zend_observer_maybe_fcall_call_end(
+	zend_execute_data *execute_data,
+	zval *return_value);
+
+// Call during minit/startup ONLY
+ZEND_API void zend_observer_fcall_register(zend_observer_fcall_init init) {
+	/* We don't want to get an extension handle unless an ext installs an observer */
+	if (!ZEND_OBSERVER_ENABLED) {
+		zend_observer_fcall_op_array_extension =
+			zend_get_op_array_extension_handle();
+
+		/* ZEND_CALL_TRAMPOLINE has SPEC(OBSERVER) but zend_init_call_trampoline_op()
+		 * is called before any extensions have registered as an observer. So we
+		 * adjust the offset to the observed handler when we know we need to observe. */
+		ZEND_VM_SET_OPCODE_HANDLER(&EG(call_trampoline_op));
+
+		/* ZEND_HANDLE_EXCEPTION also has SPEC(OBSERVER) and no observer extensions
+		 * exist when zend_init_exception_op() is called. */
+		ZEND_VM_SET_OPCODE_HANDLER(EG(exception_op));
+		ZEND_VM_SET_OPCODE_HANDLER(EG(exception_op)+1);
+		ZEND_VM_SET_OPCODE_HANDLER(EG(exception_op)+2);
+	}
+	zend_llist_add_element(&zend_observers_fcall_list, &init);
+}
+
+// Called by engine before MINITs
+ZEND_API void zend_observer_startup(void) {
+	zend_llist_init(&zend_observers_fcall_list, sizeof(zend_observer_fcall_init), NULL, 1);
+}
+
+ZEND_API void zend_observer_activate(void) {
+	if (ZEND_OBSERVER_ENABLED) {
+		fcall_handlers_arena = zend_arena_create(4096);
+	}
+}
+
+ZEND_API void zend_observer_deactivate(void) {
+	if (fcall_handlers_arena) {
+		zend_arena_destroy(fcall_handlers_arena);
+	}
+}
+
+ZEND_API void zend_observer_shutdown(void) {
+	zend_llist_destroy(&zend_observers_fcall_list);
+}
+
+ZEND_API void zend_observer_fcall_install(zend_function *function) {
+	zend_llist_element *element;
+	zend_llist *list = &zend_observers_fcall_list;
+	zend_op_array *op_array = &function->op_array;
+
+	if (fcall_handlers_arena == NULL) {
+		return;
+	}
+
+	ZEND_ASSERT(function->type != ZEND_INTERNAL_FUNCTION);
+
+	zend_llist handlers_list;
+	zend_llist_init(&handlers_list, sizeof(zend_observer_fcall), NULL, 0);
+	for (element = list->head; element; element = element->next) {
+		zend_observer_fcall_init init;
+		memcpy(&init, element->data, sizeof init);
+		zend_observer_fcall handlers = init(function);
+		if (handlers.begin || handlers.end) {
+			zend_llist_add_element(&handlers_list, &handlers);
+		}
+	}
+
+	ZEND_ASSERT(RUN_TIME_CACHE(op_array));
+	void *ext;
+	if (handlers_list.count) {
+		size_t size = sizeof(zend_observer_fcall_cache) + (handlers_list.count - 1) * sizeof(zend_observer_fcall);
+		zend_observer_fcall_cache *cache = zend_arena_alloc(&fcall_handlers_arena, size);
+		zend_observer_fcall *handler = cache->handlers;
+		for (element = handlers_list.head; element; element = element->next) {
+			memcpy(handler++, element->data, sizeof *handler);
+		}
+		cache->end = handler;
+		ext = cache;
+	} else {
+		ext = ZEND_OBSERVER_NOT_OBSERVED;
+	}
+
+	ZEND_OBSERVER_HANDLERS(op_array) = ext;
+	zend_llist_destroy(&handlers_list);
+}
+
+ZEND_API void zend_observe_fcall_begin(
+	zend_observer_fcall_cache *cache,
+	zend_execute_data *execute_data)
+{
+	zend_observer_fcall *handler, *end = cache->end;
+	for (handler = cache->handlers; handler != end; ++handler) {
+		if (handler->begin) {
+			handler->begin(execute_data);
+		}
+	}
+}
+
+ZEND_API void zend_observer_fcall_call_end_helper(
+	zend_execute_data *execute_data,
+	zval *return_value)
+{
+	zend_function *func = execute_data->func;
+	ZEND_ASSUME(ZEND_OBSERVABLE_FN(func->common.fn_flags));
+	void *observer_handlers = ZEND_OBSERVER_HANDLERS(&func->op_array);
+	// TODO: Fix exceptions from generators
+	// ZEND_ASSERT(observer_handlers);
+	if (observer_handlers && observer_handlers != ZEND_OBSERVER_NOT_OBSERVED) {
+		zend_observer_fcall_cache *cache = observer_handlers;
+		zend_observe_fcall_end(cache, execute_data, return_value);
+	}
+}
+
+ZEND_API void zend_observe_fcall_end(
+	zend_observer_fcall_cache *cache,
+	zend_execute_data *execute_data,
+	zval *return_value)
+{
+	zend_observer_fcall *handler = cache->end, *end = cache->handlers;
+	while (handler-- != end) {
+		if (handler->end) {
+			handler->end(execute_data, return_value);
+		}
+	}
+}
+
+

Zend/zend_observer.h

@@ -0,0 +1,115 @@
+/*
+   +----------------------------------------------------------------------+
+   | Zend Engine                                                          |
+   +----------------------------------------------------------------------+
+   | Copyright (c) Zend Technologies Ltd. (http://www.zend.com)           |
+   +----------------------------------------------------------------------+
+   | This source file is subject to version 2.00 of the Zend license,     |
+   | that is bundled with this package in the file LICENSE, and is        |
+   | available through the world-wide-web at the following url:           |
+   | http://www.zend.com/license/2_00.txt.                                |
+   | If you did not receive a copy of the Zend license and are unable to  |
+   | obtain it through the world-wide-web, please send a note to          |
+   | license@zend.com so we can mail you a copy immediately.              |
+   +----------------------------------------------------------------------+
+   | Authors: Levi Morrison <levim@php.net>                               |
+   |          Sammy Kaye Powers <sammyk@php.net>                          |
+   +----------------------------------------------------------------------+
+*/
+
+#ifndef ZEND_OBSERVER_H
+#define ZEND_OBSERVER_H
+
+#include "zend.h"
+#include "zend_compile.h"
+
+BEGIN_EXTERN_C()
+
+extern ZEND_API int zend_observer_fcall_op_array_extension;
+
+#define ZEND_OBSERVER_ENABLED (zend_observer_fcall_op_array_extension != -1)
+
+#define ZEND_OBSERVER_HANDLERS(op_array) \
+	ZEND_OP_ARRAY_EXTENSION(op_array, zend_observer_fcall_op_array_extension)
+
+#define ZEND_OBSERVER_NOT_OBSERVED ((void *) 2)
+
+#define ZEND_OBSERVABLE_FN(fn_flags) \
+	(ZEND_OBSERVER_ENABLED && \
+		!(fn_flags & (ZEND_ACC_CALL_VIA_TRAMPOLINE | ZEND_ACC_FAKE_CLOSURE)))
+
+struct zend_observer_fcall {
+	void (*begin)(zend_execute_data *execute_data);
+	void (*end)(zend_execute_data *execute_data, zval *retval);
+};
+typedef struct zend_observer_fcall zend_observer_fcall;
+
+struct zend_observer_fcall_cache {
+	// points after the last handler
+	zend_observer_fcall *end;
+	// a variadic array using "struct hack"
+	zend_observer_fcall handlers[1];
+};
+typedef struct zend_observer_fcall_cache zend_observer_fcall_cache;
+
+/* If the fn should not be observed then return {NULL, NULL} */
+typedef zend_observer_fcall(*zend_observer_fcall_init)(zend_function *func);
+
+// Call during minit/startup ONLY
+ZEND_API void zend_observer_fcall_register(zend_observer_fcall_init init);
+
+ZEND_API void zend_observer_startup(void); // Called by engine before MINITs
+ZEND_API void zend_observer_activate(void);
+ZEND_API void zend_observer_deactivate(void);
+ZEND_API void zend_observer_shutdown(void);
+
+ZEND_API void zend_observer_fcall_install(zend_function *function);
+
+ZEND_API void zend_observe_fcall_begin(
+	zend_observer_fcall_cache *cache,
+	zend_execute_data *execute_data);
+
+ZEND_API void zend_observe_fcall_end(
+	zend_observer_fcall_cache *cache,
+	zend_execute_data *execute_data,
+	zval *return_value);
+
+ZEND_API void zend_observer_fcall_call_end_helper(
+	zend_execute_data *execute_data,
+	zval *return_value);
+
+ZEND_API zend_always_inline void zend_observer_maybe_fcall_call_begin(
+	zend_execute_data *execute_data)
+{
+	ZEND_ASSUME(execute_data->func);
+	zend_op_array *op_array = &execute_data->func->op_array;
+	uint32_t fn_flags = op_array->fn_flags;
+	if (ZEND_OBSERVABLE_FN(fn_flags) && !(fn_flags & ZEND_ACC_GENERATOR)) {
+		void *observer_handlers = ZEND_OBSERVER_HANDLERS(op_array);
+		if (!observer_handlers) {
+			zend_observer_fcall_install((zend_function *)op_array);
+			observer_handlers = ZEND_OBSERVER_HANDLERS(op_array);
+		}
+
+		ZEND_ASSERT(observer_handlers);
+		if (observer_handlers != ZEND_OBSERVER_NOT_OBSERVED) {
+			zend_observe_fcall_begin(
+				(zend_observer_fcall_cache *)observer_handlers,
+				execute_data);
+		}
+	}
+}
+
+ZEND_API zend_always_inline void zend_observer_maybe_fcall_call_end(
+	zend_execute_data *execute_data,
+	zval *return_value)
+{
+	zend_function *func = execute_data->func;
+	if (ZEND_OBSERVABLE_FN(func->common.fn_flags)) {
+		zend_observer_fcall_call_end_helper(execute_data, return_value);
+	}
+}
+
+END_EXTERN_C()
+
+#endif /* ZEND_OBSERVER_H */