Deprecate internal_handler(), replace with EventRegistry::Register()

Added a couple explicit event declarations that were missing: "net_done"
and "dns_mapping_name_changed".

aux/bifcl

@@ -1 +1 @@
-Subproject commit 071a1517a73bde131da42fe35cac05a3503340be
+Subproject commit 970c09875a4bcfb61981d7b629e732f9a0f322ef

doc

@@ -1 +1 @@
-Subproject commit ddc898c4a7ccea56f7ed74504a00e905639d7ddf
+Subproject commit 39462e3651facf49a71f6abaa80b3b0e5f313bf6

scripts/base/init-bare.zeek

@@ -1870,9 +1870,6 @@ type gtp_delete_pdp_ctx_response_elements: record {
 @load base/frameworks/supervisor/api
 @load base/bif/supervisor.bif
 
-global done_with_network = F;
-event net_done(t: time) { done_with_network = T; }
-
 ## Internal function.
 function add_interface(iold: string, inew: string): string
 	{
@@ -5272,3 +5269,6 @@ const bits_per_uid: count = 96 &redef;
 ## to generate installation-unique file IDs (the *id* field of :zeek:see:`fa_file`).
 const digest_salt = "Please change this value." &redef;
 
+global done_with_network = F;
+event net_done(t: time)
+	{ done_with_network = T; }

src/DNS_Mgr.cc

@@ -36,7 +36,8 @@
 #include "Event.h"
 #include "Net.h"
 #include "Val.h"
-#include "Var.h"
+#include "NetVar.h"
+#include "ID.h"
 #include "Reporter.h"
 #include "IntrusivePtr.h"
 #include "iosource/Manager.h"
@@ -380,10 +381,6 @@ DNS_Mgr::DNS_Mgr(DNS_MgrMode arg_mode)
 
 	mode = arg_mode;
 
-	dns_mapping_valid = dns_mapping_unverified = dns_mapping_new_name =
-		dns_mapping_lost_name = dns_mapping_name_changed =
-			dns_mapping_altered =  nullptr;
-
 	dm_rec = nullptr;
 
 	cache_name = dir = nullptr;
@@ -455,13 +452,6 @@ void DNS_Mgr::InitSource()
 
 void DNS_Mgr::InitPostScript()
 	{
-	dns_mapping_valid = internal_handler("dns_mapping_valid");
-	dns_mapping_unverified = internal_handler("dns_mapping_unverified");
-	dns_mapping_new_name = internal_handler("dns_mapping_new_name");
-	dns_mapping_lost_name = internal_handler("dns_mapping_lost_name");
-	dns_mapping_name_changed = internal_handler("dns_mapping_name_changed");
-	dns_mapping_altered = internal_handler("dns_mapping_altered");
-
 	dm_rec = zeek::id::lookup_type("dns_mapping")->AsRecordType();
 
 	// Registering will call Init()

src/DNS_Mgr.h

@@ -149,14 +149,6 @@ protected:
 
 	bool did_init;
 
-	// DNS-related events.
-	EventHandlerPtr dns_mapping_valid;
-	EventHandlerPtr dns_mapping_unverified;
-	EventHandlerPtr dns_mapping_new_name;
-	EventHandlerPtr dns_mapping_lost_name;
-	EventHandlerPtr dns_mapping_name_changed;
-	EventHandlerPtr dns_mapping_altered;
-
 	RecordType* dm_rec;
 
 	typedef std::list<LookupCallback*> CallbackList;

src/EventRegistry.cc

@@ -6,6 +6,26 @@
 EventRegistry::EventRegistry() = default;
 EventRegistry::~EventRegistry() noexcept = default;
 
+EventHandlerPtr EventRegistry::Register(const char* name)
+	{
+	// If there already is an entry in the registry, we have a
+	// local handler on the script layer.
+	EventHandler* h = event_registry->Lookup(name);
+
+	if ( h )
+		{
+		h->SetUsed();
+		return h;
+		}
+
+	h = new EventHandler(name);
+	event_registry->Register(h);
+
+	h->SetUsed();
+
+	return h;
+	}
+
 void EventRegistry::Register(EventHandlerPtr handler)
 	{
 	handlers[std::string(handler->Name())] = std::unique_ptr<EventHandler>(handler.Ptr());

src/EventRegistry.h

@@ -17,6 +17,14 @@ public:
 	EventRegistry();
 	~EventRegistry() noexcept;
 
+	/**
+	 * Performs a lookup for an existing event handler and returns it
+	 * if one exists, or else creates one, registers it, and returns it.
+	 * @param name  The name of the event handler to lookup/register.
+	 * @return  The event handler.
+	 */
+	EventHandlerPtr Register(const char* name);
+
 	void Register(EventHandlerPtr handler);
 
 	// Return nil if unknown.

src/Var.cc

@@ -776,19 +776,5 @@ Func* internal_func(const char* name)
 
 EventHandlerPtr internal_handler(const char* name)
 	{
-	// If there already is an entry in the registry, we have a
-	// local handler on the script layer.
-	EventHandler* h = event_registry->Lookup(name);
-	if ( h )
-		{
-		h->SetUsed();
-		return h;
-		}
-
-	h = new EventHandler(name);
-	event_registry->Register(h);
-
-	h->SetUsed();
-
-	return h;
+	return event_registry->Register(name);
 	}

src/Var.h

@@ -73,4 +73,5 @@ extern BroType* internal_type(const char* name);
 [[deprecated("Remove in v4.1.  Use zeek::id::lookup_func().")]]
 extern Func* internal_func(const char* name);
 
+[[deprecated("Remove in v4.1.  Use event_registry->Register().")]]
 extern EventHandlerPtr internal_handler(const char* name);

src/bro-bif.h

@@ -8,4 +8,4 @@
 #include "Event.h"
 #include "Reporter.h"
 #include "ID.h"
-#include "Var.h" // for internal_handler()
+#include "EventRegistry.h"

src/event.bif

@@ -61,6 +61,24 @@ event zeek_init%(%);
 ##    is not generated.
 event zeek_done%(%);
 
+## Generated as one of the first steps of Zeek's main-loop termination, just
+## before it starts to flush any remaining events/timers/state. The event
+## engine generates this event when Zeek is about to terminate, either due to
+## having exhausted reading its input trace file(s), receiving a termination
+## signal, or because Zeek was run without a network input source and has
+## finished executing any global statements.  This event comes before
+## :zeek:see:`zeek_init`.
+##
+## t: The time at with the Zeek-termination process started.
+##
+## .. zeek:see:: zeek_init zeek_done
+##
+## .. note::
+##
+##    If Zeek terminates due to an invocation of :zeek:id:`exit`, then this event
+##    is not generated.
+event net_done%(t: time%);
+
 ## Generated when network time is initialized. The event engine generates this
 ## event after the network time has been determined but before processing of
 ## packets is started.
@@ -820,6 +838,20 @@ event dns_mapping_new_name%(dm: dns_mapping%);
 ##    dns_mapping_valid
 event dns_mapping_lost_name%(dm: dns_mapping%);
 
+## Generated when an internal DNS lookup returns a different host name than
+## in the past.  Zeek keeps an internal DNS cache for host names
+## and IP addresses it has already resolved. This event is generated when
+## on a subsequent lookup we receive an answer that has a different host
+## string than we already have in the cache.
+##
+## prev: A record describing the old resolver result.
+#
+## latest: A record describing the new resolver result.
+##
+## .. zeek:see:: dns_mapping_altered dns_mapping_new_name dns_mapping_unverified
+##    dns_mapping_valid
+event dns_mapping_name_changed%(prev: dns_mapping, latest: dns_mapping%);
+
 ## Generated when an internal DNS lookup produced a different result than in
 ## the past.  Zeek keeps an internal DNS cache for host names and IP addresses
 ## it has already resolved. This event is generated when a subsequent lookup

src/input/Manager.cc

@@ -192,7 +192,7 @@ Manager::AnalysisStream::~AnalysisStream()
 Manager::Manager()
 	: plugin::ComponentManager<input::Tag, input::Component>("Input", "Reader")
 	{
-	end_of_data = internal_handler("Input::end_of_data");
+	end_of_data = event_registry->Register("Input::end_of_data");
 	}
 
 Manager::~Manager()

src/zeek-setup.cc

@@ -101,7 +101,6 @@ trigger::Manager* trigger_mgr = nullptr;
 
 std::vector<std::string> zeek_script_prefixes;
 Stmt* stmts;
-EventHandlerPtr net_done = nullptr;
 RuleMatcher* rule_matcher = nullptr;
 EventRegistry* event_registry = nullptr;
 ProfileLogger* profiling_logger = nullptr;
@@ -269,7 +268,6 @@ void terminate_bro()
 
 	brofiler.WriteStats();
 
-	EventHandlerPtr zeek_done = internal_handler("zeek_done");
 	if ( zeek_done )
 		mgr.Enqueue(zeek_done, zeek::Args{});
 
@@ -740,8 +738,6 @@ zeek::detail::SetupResult zeek::detail::setup(int argc, char** argv,
 	if ( dns_type != DNS_PRIME )
 		net_init(options.interface, options.pcap_file, options.pcap_output_file, options.use_watchdog);
 
-	net_done = internal_handler("net_done");
-
 	if ( ! g_policy_debug )
 		{
 		(void) setsignal(SIGTERM, sig_handler);
@@ -797,8 +793,7 @@ zeek::detail::SetupResult zeek::detail::setup(int argc, char** argv,
 		// we don't have any other source for it.
 		net_update_time(current_time());
 
-	EventHandlerPtr zeek_init = internal_handler("zeek_init");
-	if ( zeek_init )	//### this should be a function
+	if ( zeek_init )
 		mgr.Enqueue(zeek_init, zeek::Args{});
 
 	EventRegistry::string_list dead_handlers =