Deprecate HOOK_BRO_OBJ_DTOR and related methods

NEWS

@@ -50,6 +50,9 @@ Deprecated Functionality
 - ``LogAscii::logdir`` and per-writer log directories have been
   deprecated in favor of the new ``Log::default_logdir``.
 
+- The HOOK_BRO_OBJ_DTOR hook and associated methods have been deprecated. They
+  are replaced by the HOOK_OBJ_DTOR hook and methods.
+
 Zeek 5.0.0
 ==========
 

src/Obj.cc

@@ -60,7 +60,13 @@ int Obj::suppress_errors = 0;
 Obj::~Obj()
 	{
 	if ( notify_plugins )
+		{
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 		PLUGIN_HOOK_VOID(HOOK_BRO_OBJ_DTOR, HookBroObjDtor(this));
+#pragma GCC diagnostic pop
+		PLUGIN_HOOK_VOID(HOOK_OBJ_DTOR, HookObjDtor(this));
+		}
 
 	delete location;
 	}

src/plugin/Manager.cc

@@ -669,6 +669,11 @@ void Manager::RequestBroObjDtor(Obj* obj, Plugin* plugin)
 	obj->NotifyPluginsOnDtor();
 	}
 
+void Manager::RequestObjDtor(Obj* obj, Plugin* plugin)
+	{
+	obj->NotifyPluginsOnDtor();
+	}
+
 int Manager::HookLoadFile(const Plugin::LoadType type, const string& file, const string& resolved)
 	{
 	HookArgumentList args;
@@ -905,6 +910,29 @@ void Manager::HookBroObjDtor(void* obj) const
 		MetaHookPost(HOOK_BRO_OBJ_DTOR, args, HookArgument());
 	}
 
+void Manager::HookObjDtor(void* obj) const
+	{
+	HookArgumentList args;
+
+	if ( HavePluginForHook(META_HOOK_PRE) )
+		{
+		args.push_back(HookArgument(obj));
+		MetaHookPre(HOOK_OBJ_DTOR, args);
+		}
+
+	hook_list* l = hooks[HOOK_OBJ_DTOR];
+
+	if ( l )
+		for ( hook_list::iterator i = l->begin(); i != l->end(); ++i )
+			{
+			Plugin* p = (*i).second;
+			p->HookObjDtor(obj);
+			}
+
+	if ( HavePluginForHook(META_HOOK_POST) )
+		MetaHookPost(HOOK_OBJ_DTOR, args, HookArgument());
+	}
+
 void Manager::HookLogInit(const std::string& writer, const std::string& instantiating_filter,
                           bool local, bool remote, const logging::WriterBackend::WriterInfo& info,
                           int num_fields, const threading::Field* const* fields) const

src/plugin/Manager.h

@@ -226,7 +226,19 @@ public:
 	 *
 	 * @param plugin The plugin expressing interest.
 	 */
-	void RequestBroObjDtor(Obj* obj, Plugin* plugin);
+	[[deprecated("Remove in v6.1. Use RequestObjDtor.")]] void RequestBroObjDtor(Obj* obj,
+	                                                                             Plugin* plugin);
+
+	/**
+	 * Register interest in the destruction of a Obj instance. When Zeek's
+	 * reference counting triggers the objects destructor to run, the \a
+	 * HookObjDtor will be called.
+	 *
+	 * @param handler The object being interested in.
+	 *
+	 * @param plugin The plugin expressing interest.
+	 */
+	void RequestObjDtor(Obj* obj, Plugin* plugin);
 
 	// Hook entry functions.
 
@@ -321,10 +333,16 @@ public:
 	void HookDrainEvents() const;
 
 	/**
-	 * Hook that informs plugins that an BroObj is being destroyed. Will be
+	 * Hook that informs plugins that an Obj is being destroyed. Will be
 	 * called only for objects that a plugin has expressed interest in.
 	 */
-	void HookBroObjDtor(void* obj) const;
+	[[deprecated("Remove in v6.1. Use HookObjDtor.")]] void HookBroObjDtor(void* obj) const;
+
+	/**
+	 * Hook that informs plugins that an Obj is being destroyed. Will be
+	 * called only for objects that a plugin has expressed interest in.
+	 */
+	void HookObjDtor(void* obj) const;
 
 	/**
 	 * Hook into log initialization. This method will be called when a

src/plugin/Plugin.cc

@@ -33,6 +33,7 @@ const char* hook_name(HookType h)
 		"LogWrite",
 		"Reporter",
 		"UnprocessedPacket",
+		"ObjDtor",
 		// MetaHooks
 		"MetaHookPre",
 		"MetaHookPost",
@@ -385,6 +386,11 @@ void Plugin::RequestBroObjDtor(Obj* obj)
 	plugin_mgr->RequestBroObjDtor(obj, this);
 	}
 
+void Plugin::RequestObjDtor(Obj* obj)
+	{
+	plugin_mgr->RequestObjDtor(obj, this);
+	}
+
 int Plugin::HookLoadFile(const LoadType type, const std::string& file, const std::string& resolved)
 	{
 	return -1;
@@ -416,6 +422,8 @@ void Plugin::HookSetupAnalyzerTree(Connection* conn) { }
 
 void Plugin::HookBroObjDtor(void* obj) { }
 
+void Plugin::HookObjDtor(void* obj) { }
+
 void Plugin::HookLogInit(const std::string& writer, const std::string& instantiating_filter,
                          bool local, bool remote, const logging::WriterBackend::WriterInfo& info,
                          int num_fields, const threading::Field* const* fields)

src/plugin/Plugin.h

@@ -62,14 +62,15 @@ enum HookType
 	HOOK_LOAD_FILE_EXT, //< Activates Plugin::HookLoadFileExtended().
 	HOOK_CALL_FUNCTION, //< Activates Plugin::HookCallFunction().
 	HOOK_QUEUE_EVENT, //< Activates Plugin::HookQueueEvent().
-	HOOK_DRAIN_EVENTS, //< Activates Plugin::HookDrainEvents()
+	HOOK_DRAIN_EVENTS, //< Activates Plugin::HookDrainEvents().
-	HOOK_UPDATE_NETWORK_TIME, //< Activates Plugin::HookUpdateNetworkTime.
+	HOOK_UPDATE_NETWORK_TIME, //< Activates Plugin::HookUpdateNetworkTime().
-	HOOK_BRO_OBJ_DTOR, //< Activates Plugin::HookBroObjDtor.
+	HOOK_BRO_OBJ_DTOR [[deprecated("Remove in v6.1. Use HOOK_OBJ_DTOR.")]],
-	HOOK_SETUP_ANALYZER_TREE, //< Activates Plugin::HookAddToAnalyzerTree
+	HOOK_SETUP_ANALYZER_TREE, //< Activates Plugin::HookAddToAnalyzerTree().
-	HOOK_LOG_INIT, //< Activates Plugin::HookLogInit
+	HOOK_LOG_INIT, //< Activates Plugin::HookLogInit().
-	HOOK_LOG_WRITE, //< Activates Plugin::HookLogWrite
+	HOOK_LOG_WRITE, //< Activates Plugin::HookLogWrite().
-	HOOK_REPORTER, //< Activates Plugin::HookReporter
+	HOOK_REPORTER, //< Activates Plugin::HookReporter().
-	HOOK_UNPROCESSED_PACKET, //<Activates Plugin::HookUnprocessedPacket
+	HOOK_UNPROCESSED_PACKET, //<Activates Plugin::HookUnprocessedPacket().
+	HOOK_OBJ_DTOR, //< Activates Plugin::HookObjDtor().
 
 	// Meta hooks.
 	META_HOOK_PRE, //< Activates Plugin::MetaHookPre().
@@ -822,11 +823,22 @@ protected:
 	 * Zeek's reference counting triggers the objects destructor to run,
 	 * \a HookBroObjDtor will be called.
 	 *
-	 * Note that his can get expensive if triggered for many objects.
+	 * Note that this can get expensive if triggered for many objects.
 	 *
-	 * @param handler The object being interested in.
+	 * @param obj The object being interested in.
 	 */
-	void RequestBroObjDtor(Obj* obj);
+	[[deprecated("Remove in v6.1. Use RequestObjDtor.")]] void RequestBroObjDtor(Obj* obj);
+
+	/**
+	 * Registers interest in the destruction of a Obj instance. When
+	 * Zeek's reference counting triggers the objects destructor to run,
+	 * \a HookObjDtor will be called.
+	 *
+	 * Note that this can get expensive if triggered for many objects.
+	 *
+	 * @param obj The object being interested in.
+	 */
+	void RequestObjDtor(Obj* obj);
 
 	// Hook functions.
 
@@ -972,7 +984,19 @@ protected:
 	 * object is already considered invalid and the pointer must not be
 	 * dereferenced.
 	 */
-	virtual void HookBroObjDtor(void* obj);
+	[[deprecated("Remove in v6.1. Use HookObjDtor.")]] virtual void HookBroObjDtor(void* obj);
+
+	/**
+	 * Hook for destruction of objects registered with
+	 * RequestObjDtor(). When Zeek's reference counting triggers the
+	 * objects destructor to run, this method will be run. It may also
+	 * run for other objects that this plugin has not registered for.
+	 *
+	 * @param obj A pointer to the object being destroyed. Note that the
+	 * object is already considered invalid and the pointer must not be
+	 * dereferenced.
+	 */
+	virtual void HookObjDtor(void* obj);
 
 	/**
 	 * Hook into log initialization. This method will be called when a

testing/btest/Baseline/plugins.hooks/output

@@ -4447,6 +4447,7 @@ XXXXXXXXXX.XXXXXX   MetaHookPost  CallFunction(filter_change_tracking, <null>, (
 XXXXXXXXXX.XXXXXX   MetaHookPost  CallFunction(get_net_stats, <frame>, ()) -> <no result>
 XXXXXXXXXX.XXXXXX   MetaHookPost  CallFunction(new_connection, <null>, ([id=[orig_h=141.142.228.5, orig_p=59856/tcp, resp_h=192.150.187.43, resp_p=80/tcp], orig=[size=0, state=0, num_pkts=0, num_bytes_ip=0, flow_label=0, l2_addr=c8:bc:c8:96:d2:a0], resp=[size=0, state=0, num_pkts=0, num_bytes_ip=0, flow_label=0, l2_addr=00:10:db:88:d2:ef], start_time=XXXXXXXXXX.XXXXXX, duration=0 secs, service={}, history=, uid=CHhAvVGS1DHFjwGM9, tunnel=<uninitialized>, vlan=<uninitialized>, inner_vlan=<uninitialized>, dpd=<uninitialized>, dpd_state=<uninitialized>, removal_hooks=<uninitialized>, conn=<uninitialized>, extract_orig=F, extract_resp=F, thresholds=<uninitialized>, dce_rpc=<uninitialized>, dce_rpc_state=<uninitialized>, dce_rpc_backing=<uninitialized>, dhcp=<uninitialized>, dnp3=<uninitialized>, dns=<uninitialized>, dns_state=<uninitialized>, ftp=<uninitialized>, ftp_data_reuse=F, ssl=<uninitialized>, http=<uninitialized>, http_state=<uninitialized>, irc=<uninitialized>, krb=<uninitialized>, modbus=<uninitialized>, mysql=<uninitialized>, ntlm=<uninitialized>, ntp=<uninitialized>, radius=<uninitialized>, rdp=<uninitialized>, rfb=<uninitialized>, sip=<uninitialized>, sip_state=<uninitialized>, snmp=<uninitialized>, smb_state=<uninitialized>, smtp=<uninitialized>, smtp_state=<uninitialized>, socks=<uninitialized>, ssh=<uninitialized>, syslog=<uninitialized>])) -> <no result>
 XXXXXXXXXX.XXXXXX   MetaHookPost  DrainEvents() -> <void>
+XXXXXXXXXX.XXXXXX   MetaHookPost  ObjDtor(<void ptr>) -> <void>
 XXXXXXXXXX.XXXXXX   MetaHookPost  QueueEvent(Broker::log_flush()) -> false
 XXXXXXXXXX.XXXXXX   MetaHookPost  QueueEvent(ChecksumOffloading::check()) -> false
 XXXXXXXXXX.XXXXXX   MetaHookPost  QueueEvent(filter_change_tracking()) -> false
@@ -4462,6 +4463,7 @@ XXXXXXXXXX.XXXXXX   MetaHookPre   CallFunction(filter_change_tracking, <null>, (
 XXXXXXXXXX.XXXXXX   MetaHookPre   CallFunction(get_net_stats, <frame>, ())
 XXXXXXXXXX.XXXXXX   MetaHookPre   CallFunction(new_connection, <null>, ([id=[orig_h=141.142.228.5, orig_p=59856/tcp, resp_h=192.150.187.43, resp_p=80/tcp], orig=[size=0, state=0, num_pkts=0, num_bytes_ip=0, flow_label=0, l2_addr=c8:bc:c8:96:d2:a0], resp=[size=0, state=0, num_pkts=0, num_bytes_ip=0, flow_label=0, l2_addr=00:10:db:88:d2:ef], start_time=XXXXXXXXXX.XXXXXX, duration=0 secs, service={}, history=, uid=CHhAvVGS1DHFjwGM9, tunnel=<uninitialized>, vlan=<uninitialized>, inner_vlan=<uninitialized>, dpd=<uninitialized>, dpd_state=<uninitialized>, removal_hooks=<uninitialized>, conn=<uninitialized>, extract_orig=F, extract_resp=F, thresholds=<uninitialized>, dce_rpc=<uninitialized>, dce_rpc_state=<uninitialized>, dce_rpc_backing=<uninitialized>, dhcp=<uninitialized>, dnp3=<uninitialized>, dns=<uninitialized>, dns_state=<uninitialized>, ftp=<uninitialized>, ftp_data_reuse=F, ssl=<uninitialized>, http=<uninitialized>, http_state=<uninitialized>, irc=<uninitialized>, krb=<uninitialized>, modbus=<uninitialized>, mysql=<uninitialized>, ntlm=<uninitialized>, ntp=<uninitialized>, radius=<uninitialized>, rdp=<uninitialized>, rfb=<uninitialized>, sip=<uninitialized>, sip_state=<uninitialized>, snmp=<uninitialized>, smb_state=<uninitialized>, smtp=<uninitialized>, smtp_state=<uninitialized>, socks=<uninitialized>, ssh=<uninitialized>, syslog=<uninitialized>]))
 XXXXXXXXXX.XXXXXX   MetaHookPre   DrainEvents()
+XXXXXXXXXX.XXXXXX   MetaHookPre   ObjDtor(<void ptr>)
 XXXXXXXXXX.XXXXXX   MetaHookPre   QueueEvent(Broker::log_flush())
 XXXXXXXXXX.XXXXXX   MetaHookPre   QueueEvent(ChecksumOffloading::check())
 XXXXXXXXXX.XXXXXX   MetaHookPre   QueueEvent(filter_change_tracking())
@@ -4469,6 +4471,7 @@ XXXXXXXXXX.XXXXXX   MetaHookPre   QueueEvent(new_connection([id=[orig_h=141.142.
 XXXXXXXXXX.XXXXXX   MetaHookPre   SetupAnalyzerTree(XXXXXXXXXX.XXXXXX(XXXXXXXXXX.XXXXXX) TCP 141.142.228.5:59856 -> 192.150.187.43:80)
 XXXXXXXXXX.XXXXXX   MetaHookPre   UpdateNetworkTime(XXXXXXXXXX.XXXXXX)
 XXXXXXXXXX.XXXXXX  | HookBroObjDtor
+XXXXXXXXXX.XXXXXX  | HookObjDtor  
 XXXXXXXXXX.XXXXXX  | HookUpdateNetworkTime XXXXXXXXXX.XXXXXX
 XXXXXXXXXX.XXXXXX | HookCallFunction Broker::__flush_logs()
 XXXXXXXXXX.XXXXXX | HookCallFunction Broker::flush_logs()

testing/btest/plugins/hooks-plugin/src/Plugin.cc

@@ -31,6 +31,7 @@ zeek::plugin::Configuration Plugin::Configure()
 	EnableHook(zeek::plugin::HOOK_LOG_INIT);
 	EnableHook(zeek::plugin::HOOK_LOG_WRITE);
 	EnableHook(zeek::plugin::HOOK_UNPROCESSED_PACKET);
+	EnableHook(zeek::plugin::HOOK_OBJ_DTOR);
 
 	zeek::plugin::Configuration config;
 	config.name = "Demo::Hooks";
@@ -156,6 +157,11 @@ void Plugin::HookBroObjDtor(void* obj)
 	fprintf(stderr, "%.6f  %-15s\n", zeek::run_state::network_time, "| HookBroObjDtor");
 	}
 
+void Plugin::HookObjDtor(void* obj)
+	{
+	fprintf(stderr, "%.6f  %-15s\n", zeek::run_state::network_time, "| HookObjDtor");
+	}
+
 void Plugin::MetaHookPre(zeek::plugin::HookType hook, const zeek::plugin::HookArgumentList& args)
 	{
 	zeek::ODesc d;

testing/btest/plugins/hooks-plugin/src/Plugin.h

@@ -16,6 +16,7 @@ protected:
 	void HookDrainEvents() override;
 	void HookUpdateNetworkTime(double network_time) override;
 	void HookBroObjDtor(void* obj) override;
+	void HookObjDtor(void* obj) override;
 	void HookLogInit(const std::string& writer, const std::string& instantiating_filter, bool local, bool remote,
 	                 const zeek::logging::WriterBackend::WriterInfo& info, int num_fields,
 	                 const zeek::threading::Field* const* fields) override;