Created signal_get_uniq_id() macro. Added some documentation about

signals to design.txt.


git-svn-id: http://svn.irssi.org/repos/irssi/trunk@381 dbcabf3a-b0e7-0310-adc4-f8d773084564

docs/design.txt

@@ -35,6 +35,45 @@
  about the chat protocols. This should allow implementing modules to
  whatever chat protocols and with whatever frontends easily.
 
+ ** Signals
+
+ Communication between different modules are done with "signals". They are
+ not related to UNIX signals in any way, you could more like think of them
+ as "events" - which might be a better name for them, but I don't really
+ want to change it anymore :)
+
+ So, you send signal with signal_emit() and it's sent to all modules that
+ have grabbed it by calling signal_add() in their init function. For
+ example:
+
+   signal_emit("mysignal", 1, "hello");
+
+ Sends a "mysignal" function with one argument "hello" - before that, you
+ should have grabbed the signal somewhere else with:
+
+   static void sig_mysignal(const char *arg1)
+   {
+     /* arg1 contains "hello" */
+   }
+
+   signal_add("mysignal", (SIGNAL_FUNC) sig_mysignal);
+
+ There are three different signal_add() functions which you can use to
+ specify if you want to grab the signal first, "normally" or last. You can
+ also stop the signal from going any further.
+
+ Emitting signal with it's name creates a small overhead since it has to
+ look up the signal's numeric ID first, after which it looks up the signal
+ structure. This is done because if you call a signal _really_ often,
+ it's faster to find it with it's numeric ID instead of the string. You
+ can use signal_get_uniq_id() macro to convert the signal name into ID -
+ you'll have to do this only once! - and use signal_emit_id() to emit the
+ signal. Don't bother to do this unless your signal is sent (or could be
+ sent) several times in a second.
+
+ See src/core/signals.h for defination of the signal function, and
+ signals.txt for a list of signals.
+
 
  ** lib-popt
 

docs/signals.txt

@@ -1,10 +1,13 @@
+List of signals irssi emits - see design.txt for more information about
+signals.
+
 IRC base
 --------
 
 * Requires to work properly:
 
  "gui exit"
-"send command", char *command, SERVER_REC, WI_ITEM_REC
+ "send command", char *command, SERVER_REC, WI_ITEM_REC
 
 * Provides signals:
 

src/core/commands.c

@@ -554,7 +554,7 @@ void commands_init(void)
 	cmdget_funcs = NULL;
 	current_command = NULL;
 
-	signal_default_command = module_get_uniq_id_str("signals", "default command");
+	signal_default_command = signal_get_uniq_id("default command");
 
 	settings_add_str("misc", "cmdchars", "/");
 	signal_add("send command", (SIGNAL_FUNC) event_command);

src/core/pidwait.c

@@ -63,7 +63,7 @@ void pidwait_init(void)
 	pids = NULL;
 	childcheck_tag = g_timeout_add(1000, (GSourceFunc) child_check, NULL);
 
-	signal_pidwait = module_get_uniq_id_str("signals", "pidwait");
+	signal_pidwait = signal_get_uniq_id("pidwait");
 }
 
 void pidwait_deinit(void)

src/core/rawlog.c

@@ -154,7 +154,7 @@ static void read_settings(void)
 
 void rawlog_init(void)
 {
-	signal_rawlog = module_get_uniq_id_str("signals", "rawlog");
+	signal_rawlog = signal_get_uniq_id("rawlog");
 
 	settings_add_int("history", "rawlog_lines", 200);
 	read_settings();

src/core/signals.c

@@ -52,7 +52,7 @@ void signal_add_to(const char *module, int pos, const char *signal, SIGNAL_FUNC
 	g_return_if_fail(func != NULL);
 	g_return_if_fail(pos >= 0 && pos < SIGNAL_LISTS);
 
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
 
 	rec = g_hash_table_lookup(signals, GINT_TO_POINTER(signal_id));
 	if (rec == NULL) {
@@ -146,7 +146,7 @@ void signal_remove(const char *signal, SIGNAL_FUNC func)
 	g_return_if_fail(signal != NULL);
 	g_return_if_fail(func != NULL);
 
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
 
 	rec = g_hash_table_lookup(signals, GINT_TO_POINTER(signal_id));
 	found = rec == NULL ? 0 : signal_remove_from_lists(rec, signal_id, func);
@@ -251,7 +251,7 @@ int signal_emit(const char *signal, int params, ...)
 	int signal_id, ret;
 
 	/* get arguments */
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
 
 	va_start(va, params);
 	ret = signal_emitv_id(signal_id, params, va);
@@ -291,7 +291,7 @@ void signal_stop_by_name(const char *signal)
 	SIGNAL_REC *rec;
 	int signal_id;
 
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
 	rec = g_hash_table_lookup(signals, GINT_TO_POINTER(signal_id));
 	if (rec == NULL)
 		g_warning("signal_stop_by_name() : unknown signal \"%s\"", signal);

src/core/signals.h

@@ -6,6 +6,10 @@ typedef void (*SIGNAL_FUNC) (gconstpointer, gconstpointer, gconstpointer, gconst
 void signals_init(void);
 void signals_deinit(void);
 
+/* use this macro to convert the signal name to ID */
+#define signal_get_uniq_id(signal) \
+        module_get_uniq_id_str("signals", signal)
+
 /* bind a signal */
 void signal_add_to(const char *module, int pos, const char *signal, SIGNAL_FUNC func);
 #define signal_add(a, b) signal_add_to(MODULE_NAME, 1, a, b)

src/fe-common/core/printtext.c

@@ -900,10 +900,10 @@ void printtext_init(void)
 {
 	settings_add_int("misc", "timestamp_timeout", 0);
 
-	signal_gui_print_text = module_get_uniq_id_str("signals", "gui print text");
-	signal_print_text_stripped = module_get_uniq_id_str("signals", "print text stripped");
-	signal_print_text = module_get_uniq_id_str("signals", "print text");
-	signal_print_text_finished = module_get_uniq_id_str("signals", "print text finished");
+	signal_gui_print_text = signal_get_uniq_id("gui print text");
+	signal_print_text_stripped = signal_get_uniq_id("print text stripped");
+	signal_print_text = signal_get_uniq_id("print text");
+	signal_print_text_finished = signal_get_uniq_id("print text finished");
 
 	read_settings();
 	signal_add("print text", (SIGNAL_FUNC) sig_print_text);

src/irc/core/irc.c

@@ -423,10 +423,10 @@ void irc_irc_init(void)
 	signal_add("server incoming", (SIGNAL_FUNC) irc_parse_incoming_line);
 
 	current_server_event = NULL;
-	signal_send_command = module_get_uniq_id_str("signals", "send command");
-	signal_default_event = module_get_uniq_id_str("signals", "default event");
-	signal_server_event = module_get_uniq_id_str("signals", "server event");
-	signal_server_incoming = module_get_uniq_id_str("signals", "server incoming");
+	signal_send_command = signal_get_uniq_id("send command");
+	signal_default_event = signal_get_uniq_id("default event");
+	signal_server_event = signal_get_uniq_id("server event");
+	signal_server_incoming = signal_get_uniq_id("server incoming");
 }
 
 void irc_irc_deinit(void)

src/perl/irssi-perl.c

@@ -247,7 +247,7 @@ static int perl_signal_find(const char *signal, const char *func, int last)
 
 	table = last ? last_signals : first_signals;
 
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
         siglist = g_hash_table_lookup(table, GINT_TO_POINTER(signal_id));
 
 	while (siglist != NULL) {
@@ -272,7 +272,7 @@ static void perl_signal_to(const char *signal, const char *func, int last)
 		return;
 
 	rec = g_new(PERL_SIGNAL_REC, 1);
-	rec->signal_id = module_get_uniq_id_str("signals", signal);
+	rec->signal_id = signal_get_uniq_id(signal);
 	rec->signal = g_strdup(signal);
 	rec->func = g_strdup(func);
 	rec->last = last;
@@ -324,7 +324,7 @@ void perl_signal_remove(const char *signal, const char *func)
 	GSList *list;
 	int signal_id;
 
-	signal_id = module_get_uniq_id_str("signals", signal);
+	signal_id = signal_get_uniq_id(signal);
 
 	list = g_hash_table_lookup(first_signals, GINT_TO_POINTER(signal_id));
 	if (list != NULL)