WebSVN – nexmon – Blame – Rev 1 – /utilities/glib/docs/reference/gobject/tut

1

office

1

<?xml version='1.0' encoding="UTF-8"?>

2

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

3

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

4

]>

5

<chapter id="chapter-signal">

6

<title>The GObject messaging system</title>

7

8

<sect1 id="closure">

9

<title>Closures</title>

10

11

<para>

12

Closures are central to the concept of asynchronous signal delivery

13

which is widely used throughout GTK+ and GNOME applications. A closure is an

14

abstraction, a generic representation of a callback. It is a small structure

15

which contains three objects:

16

<itemizedlist>

17

<listitem><para>a function pointer (the callback itself) whose prototype looks like:

18

<informalexample><programlisting>

19

return_type function_callback (… , gpointer user_data);

20

</programlisting></informalexample>

21

</para></listitem>

22

<listitem><para>

23

the <parameter>user_data</parameter> pointer which is passed to the callback upon invocation of the closure

24

</para></listitem>

25

<listitem><para>

26

a function pointer which represents the destructor of the closure: whenever the

27

closure's refcount reaches zero, this function will be called before the closure

28

structure is freed.

</para></listitem>

</itemizedlist>

</para>

<para>

The <link linkend="GClosure"><type>GClosure</type></link> structure represents the common functionality of all

35

closure implementations: there exists a different closure implementation for

36

each separate runtime which wants to use the GObject type system.

37

<footnote><para>

38

In practice, closures sit at the boundary of language runtimes: if you are

39

writing Python code and one of your Python callbacks receives a signal from

40

a GTK+ widget, the C code in GTK+ needs to execute your Python

41

code. The closure invoked by the GTK+ object invokes the Python callback:

42

it behaves as a normal C object for GTK+ and as a normal Python object for

43

Python code.

44

</para></footnote>

45

The GObject library provides a simple <link linkend="GCClosure"><type>GCClosure</type></link> type which

46

is a specific implementation of closures to be used with C/C++ callbacks.

47

</para>

48

<para>

49

A <link linkend="GClosure"><type>GClosure</type></link> provides simple services:

50

<itemizedlist>

51

<listitem><para>

52

          Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures

53

were created for: they hide the details of callback invocation from the

54

callback invoker.</para>

55

</listitem>

56

<listitem><para>

57

Notification: the closure notifies listeners of certain events such as

58

closure invocation, closure invalidation and closure finalization. Listeners

59

          can be registered with <function><link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>

60

          (finalization notification), <function><link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function>

61

(invalidation notification) and

62

          <function><link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function> (invocation notification).

63

There exist symmetric deregistration functions for finalization and invalidation

64

          events (<function><link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function> and

65

          <function><link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>) but not for the invocation

66

process.

67

<footnote><para>

68

Closures are reference counted and notify listeners of their destruction in a two-stage

69

process: the invalidation notifiers are invoked before the finalization notifiers.

70

</para></footnote></para>

</listitem>

</itemizedlist>

</para>

<sect2>

<title>C Closures</title>

77

78

<para>

79

If you are using C or C++

80

        to connect a callback to a given event, you will either use simple <link linkend="GCClosure"><type>GCClosure</type></link>s

81

        which have a pretty minimal API or the even simpler <function><link linkend="g-signal-connect">g_signal_connect</link></function>

82

functions (which will be presented a bit later).

</para>

<para>

        <function><link linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new closure which can invoke the

87

user-provided callback_func with the user-provided

88

<parameter>user_data</parameter> as its last parameter. When the closure

89

is finalized (second stage of the destruction process), it will invoke

90

the <parameter>destroy_data</parameter> function if the user has

supplied one.

</para>

<para>

        <function><link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will create a new closure which can invoke the

96

user-provided <parameter>callback_func</parameter> with the

97

user-provided <parameter>user_data</parameter> as its first parameter

98

(instead of being the

99

        last parameter as with <function><link linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure

100

is finalized (second stage of the destruction process), it will invoke

101

the <parameter>destroy_data</parameter> function if the user has

supplied one.

</para>

</sect2>

<sect2>

<title>Non-C closures (for the fearless)</title>

108

109

<para>

110

As was explained above, closures hide the details of callback invocation. In C,

111

callback invocation is just like function invocation: it is a matter of creating

112

the correct stack frame for the called function and executing a <emphasis>call</emphasis>

113

assembly instruction.

</para>

<para>

C closure marshallers transform the array of GValues which represent

118

the parameters to the target function into a C-style function parameter list, invoke

119

the user-supplied C function with this new parameter list, get the return value of the

120

function, transform it into a GValue and return this GValue to the marshaller caller.

</para>

<para>

A generic C closure marshaller is available as

125

<link linkend="g-cclosure-marshal-generic"><function>g_cclosure_marshal_generic</function></link>

126

which implements marshalling for all function types using libffi. Custom

127

marshallers for different types are not needed apart from performance

128

critical code where the libffi-based marshaller may be too slow.

</para>

<para>

An example of a custom marshaller is given below, illustrating how

133

<type>GValue</type>s can be converted to a C function call. The

134

marshaller is for a C function which takes an integer as its first

135

parameter and returns void.

136

<informalexample><programlisting>

137

g_cclosure_marshal_VOID__INT (GClosure *closure,

138

GValue *return_value,

139

guint n_param_values,

140

const GValue *param_values,

141

gpointer invocation_hint,

142

gpointer marshal_data)

143

{

144

typedef void (*GMarshalFunc_VOID__INT) (gpointer data1,

145

gint arg_1,

146

gpointer data2);

147

register GMarshalFunc_VOID__INT callback;

148

register GCClosure *cc = (GCClosure*) closure;

149

register gpointer data1, data2;

150

151

g_return_if_fail (n_param_values == 2);

152

153

data1 = g_value_peek_pointer (param_values + 0);

154

data2 = closure->data;

155

156

callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc->callback);

157

158

callback (data1,

159

g_marshal_value_peek_int (param_values + 1),

160

data2);

161

}

162

</programlisting></informalexample>

</para>

<para>

There exist other kinds of marshallers, for example there is a generic

167

Python marshaller which is used by all Python closures (a Python closure

168

is used to invoke a callback written in Python). This Python marshaller

169

transforms the input GValue list representing the function parameters

170

into a Python tuple which is the equivalent structure in Python.

</para>

</sect2>

</sect1>

<sect1 id="signal">

177

<title>Signals</title>

178

179

<para>

180

GObject's signals have nothing to do with standard UNIX signals: they connect

181

arbitrary application-specific events with any number of listeners.

182

For example, in GTK+, every user event (keystroke or mouse move) is received

183

from the windowing system and generates a GTK+ event in the form of a signal emission

184

on the widget object instance.

</para>

<para>

Each signal is registered in the type system together with the type on which

189

it can be emitted: users of the type are said to <emphasis>connect</emphasis>

190

to the signal on a given type instance when they register a closure to be

191

invoked upon the signal emission. Users can also emit the signal by themselves

192

or stop the emission of the signal from within one of the closures connected

to the signal.

</para>

<para>

When a signal is emitted on a given type instance, all the closures

198

connected to this signal on this type instance will be invoked. All the closures

199

connected to such a signal represent callbacks whose signature looks like:

200

<informalexample><programlisting>

201

return_type function_callback (gpointer instance, …, gpointer user_data);

202

</programlisting></informalexample>

203

</para>

204

205

<sect2 id="signal-registration">

206

<title>Signal registration</title>

207

208

<para>

209

		To register a new signal on an existing type, we can use any of <function><link linkend="g-signal-newv">g_signal_newv</link></function>,

210

		<function><link linkend="g-signal-new-valist">g_signal_new_valist</link></function> or <function><link linkend="g-signal-new">g_signal_new</link></function> functions:

211

<informalexample><programlisting>

212

guint g_signal_newv (const gchar *signal_name,

213

GType itype,

214

GSignalFlags signal_flags,

215

GClosure *class_closure,

216

GSignalAccumulator accumulator,

217

gpointer accu_data,

218

GSignalCMarshaller c_marshaller,

219

GType return_type,

220

guint n_params,

221

GType *param_types);

222

</programlisting></informalexample>

223

The number of parameters to these functions is a bit intimidating but they are relatively

simple:

<itemizedlist>

<listitem><para>

<parameter>signal_name</parameter>: is a string which can be used to uniquely identify a given signal.

228

</para></listitem>

229

<listitem><para>

230

<parameter>itype</parameter>: is the instance type on which this signal can be emitted.

231

</para></listitem>

232

<listitem><para>

233

<parameter>signal_flags</parameter>: partly defines the order in which closures which were connected to the

234

signal are invoked.

235

</para></listitem>

236

<listitem><para>

237

<parameter>class_closure</parameter>: this is the default closure for the signal: if it is not NULL upon

238

the signal emission, it will be invoked upon this emission of the signal. The

239

moment where this closure is invoked compared to other closures connected to that

240

signal depends partly on the signal_flags.

241

</para></listitem>

242

<listitem><para>

243

<parameter>accumulator</parameter>: this is a function pointer which is invoked after each closure

244

has been invoked. If it returns FALSE, signal emission is stopped. If it returns

245

TRUE, signal emission proceeds normally. It is also used to compute the return

246

value of the signal based on the return value of all the invoked closures.

247

For example, an accumulator could ignore

248

<literal>NULL</literal> returns from closures; or it

249

could build a list of the values returned by the

closures.

</para></listitem>

<listitem><para>

<parameter>accumulator_data</parameter>: this pointer will be passed down to each invocation of the

254

accumulator during emission.

255

</para></listitem>

256

<listitem><para>

257

<parameter>c_marshaller</parameter>: this is the default C marshaller for any closure which is connected to

this signal.

</para></listitem>

<listitem><para>

<parameter>return_type</parameter>: this is the type of the return value of the signal.

262

</para></listitem>

263

<listitem><para>

264

<parameter>n_params</parameter>: this is the number of parameters this signal takes.

265

</para></listitem>

266

<listitem><para>

267

<parameter>param_types</parameter>: this is an array of GTypes which indicate the type of each parameter

268

of the signal. The length of this array is indicated by n_params.

</para></listitem>

</itemizedlist>

</para>

<para>

As you can see from the above definition, a signal is basically a description

275

of the closures which can be connected to this signal and a description of the

276

order in which the closures connected to this signal will be invoked.

</para>

</sect2>

<sect2 id="signal-connection">

282

<title>Signal connection</title>

283

284

<para>

285

If you want to connect to a signal with a closure, you have three possibilities:

286

<itemizedlist>

287

<listitem><para>

288

You can register a class closure at signal registration: this is a

289

system-wide operation. i.e.: the class closure will be invoked during each emission

290

of a given signal on <emphasis>any</emphasis> of the instances of the type which supports that signal.

291

</para></listitem>

292

<listitem><para>

293

		  You can use <function><link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function> which

294

overrides the class closure of a given type. It is possible to call this function

295

only on a derived type of the type on which the signal was registered.

296

This function is of use only to language bindings.

297

</para></listitem>

298

<listitem><para>

299

You can register a closure with the <function><link linkend="g-signal-connect">g_signal_connect</link></function>

300

family of functions. This is an instance-specific operation: the closure

301

will be invoked only during emission of a given signal on a given instance.

302

</para></listitem>

303

</itemizedlist>

304

It is also possible to connect a different kind of callback on a given signal:

305

emission hooks are invoked whenever a given signal is emitted whatever the instance on

306

which it is emitted. Emission hooks are used for example to get all mouse_clicked

307

emissions in an application to be able to emit the small mouse click sound.

308

		Emission hooks are connected with <function><link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>

309

		and removed with <function><link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.

</para>

</sect2>

<sect2 id="signal-emission">

315

<title>Signal emission</title>

316

317

<para>

318

		Signal emission is done through the use of the <function><link linkend="g-signal-emit">g_signal_emit</link></function> family

319

of functions.

320

<informalexample><programlisting>

321

void g_signal_emitv (const GValue *instance_and_params,

322

guint signal_id,

323

GQuark detail,

324

GValue *return_value);

325

</programlisting></informalexample>

326

<itemizedlist>

327

<listitem><para>

328

The <parameter>instance_and_params</parameter> array of GValues contains the list of input

329

parameters to the signal. The first element of the array is the

330

instance pointer on which to invoke the signal. The following elements of

331

the array contain the list of parameters to the signal.

332

</para></listitem>

333

<listitem><para>

334

<parameter>signal_id</parameter> identifies the signal to invoke.

335

</para></listitem>

336

<listitem><para>

337

<parameter>detail</parameter> identifies the specific detail of the signal to invoke. A detail is a kind of

338

magic token/argument which is passed around during signal emission and which is used

339

by closures connected to the signal to filter out unwanted signal emissions. In most

340

cases, you can safely set this value to zero. See <xref linkend="signal-detail"/> for

341

more details about this parameter.

342

</para></listitem>

343

<listitem><para>

344

<parameter>return_value</parameter> holds the return value of the last closure invoked during emission if

345

no accumulator was specified. If an accumulator was specified during signal creation,

346

this accumulator is used to calculate the return value as a function of the return

347

values of all the closures invoked during emission.

348

If no closure is invoked during

349

emission, the <parameter>return_value</parameter> is nonetheless initialized to zero/null.

</para></listitem>

</itemizedlist>

</para>

<para>

Signal emission can be decomposed in 5 steps:

356

<orderedlist>

357

<listitem><para>

358

<literal>RUN_FIRST</literal>: if the

359

<link linkend="G-SIGNAL-RUN-FIRST:CAPS"><literal>G_SIGNAL_RUN_FIRST</literal></link> flag was used

360

during signal registration and if there exists a class closure for this signal,

361

the class closure is invoked.

362

</para></listitem>

363

<listitem><para>

364

<literal>EMISSION_HOOK</literal>: if any emission hook was added to

365

the signal, they are invoked from first to last added. Accumulate return values.

366

</para></listitem>

367

<listitem><para>

368

<literal>HANDLER_RUN_FIRST</literal>: if any closure were connected

369

with the <function><link linkend="g-signal-connect">g_signal_connect</link></function> family of

370

			functions, and if they are not blocked (with the <function><link linkend="g-signal-handler-block">g_signal_handler_block</link></function>

371

family of functions) they are run here, from first to last connected.

372

</para></listitem>

373

<listitem><para>

374

<literal>RUN_LAST</literal>: if the <literal>G_SIGNAL_RUN_LAST</literal>

375

flag was set during registration and if a class closure

376

was set, it is invoked here.

377

</para></listitem>

378

<listitem><para>

379

<literal>HANDLER_RUN_LAST</literal>: if any closure were connected

380

with the <function>g_signal_connect_after</function> family of

381

functions, if they were not invoked during <literal>HANDLER_RUN_FIRST</literal> and if they

382

are not blocked, they are run here, from first to last connected.

383

</para></listitem>

384

<listitem><para>

385

<literal>RUN_CLEANUP</literal>: if the <literal>G_SIGNAL_RUN_CLEANUP</literal> flag

386

was set during registration and if a class closure was set,

387

it is invoked here. Signal emission is completed here.

</para></listitem>

</orderedlist>

</para>

<para>

If, at any point during emission (except in <literal>RUN_CLEANUP</literal> state), one of the

394

closures or emission hook stops the signal emission with

395

<function><link linkend="g-signal-stop-emission">g_signal_stop_emission</link></function>,

396

emission jumps to <literal>RUN_CLEANUP</literal> state.

</para>

<para>

If, at any point during emission, one of the closures or emission hook

401

emits the same signal on the same instance, emission is restarted from

402

the <literal>RUN_FIRST</literal> state.

</para>

<para>

The accumulator function is invoked in all states, after invocation

407

of each closure (except in <literal>RUN_EMISSION_HOOK</literal> and

408

<literal>RUN_CLEANUP</literal>). It accumulates

409

the closure return value into the signal return value and returns TRUE or

410

FALSE. If, at any point, it does not return TRUE, emission jumps

411

to <literal>RUN_CLEANUP</literal> state.

</para>

<para>

If no accumulator function was provided, the value returned by the last handler

416

run will be returned by <function><link linkend="g-signal-emit">g_signal_emit</link></function>.

</para>

</sect2>

<sect2 id="signal-detail">

423

<title>The <emphasis>detail</emphasis> argument</title>

424

425

<para>All the functions related to signal emission or signal connection have a parameter

426

named the <emphasis>detail</emphasis>. Sometimes, this parameter is hidden by the API

427

but it is always there, in one form or another.

</para>

<para>

Of the three main connection functions,

432

only one has an explicit detail parameter as a <link linkend="GQuark"><type>GQuark</type></link>:

433

<link linkend="g-signal-connect-closure-by-id"><function>g_signal_connect_closure_by_id</function></link>.

434

<footnote>

435

<para>A GQuark is an integer which uniquely represents a string. It is possible to transform

436

back and forth between the integer and string representations with the functions

437

		   <function><link linkend="g-quark-from-string">g_quark_from_string</link></function> and <function><link linkend="g-quark-to-string">g_quark_to_string</link></function>.

</para>

</footnote>

</para>

<para>

The two other functions,

443

<link linkend="g-signal-connect-closure"><function>g_signal_connect_closure</function></link> and

444

<link linkend="g-signal-connect-data"><function>g_signal_connect_data</function></link>

445

hide the detail parameter in the signal name identification.

446

Their <parameter>detailed_signal</parameter> parameter is a

447

string which identifies the name of the signal to connect to.

448

The format of this string should match

449

<emphasis>signal_name::detail_name</emphasis>. For example,

450

connecting to the signal named

451

<emphasis>notify::cursor_position</emphasis> will actually

452

connect to the signal named <emphasis>notify</emphasis> with the

453

<emphasis>cursor_position</emphasis> detail.

454

Internally, the detail string is transformed to a GQuark if it is present.

</para>

<para>

Of the four main signal emission functions, one hides it in its

459

signal name parameter:

460

<link linkend="g-signal-connect"><function>g_signal_connect</function></link>.

461

The other three have an explicit detail parameter as a

462

<link linkend="GQuark"><type>GQuark</type></link> again:

463

<link linkend="g-signal-emit"><function>g_signal_emit</function></link>,

464

<link linkend="g-signal-emitv"><function>g_signal_emitv</function></link> and

465

<link linkend="g-signal-emit-valist"><function>g_signal_emit_valist</function></link>.

</para>

<para>

If a detail is provided by the user to the emission function, it is used during emission to match

470

against the closures which also provide a detail.

471

If a closure's detail does not match the detail provided by the user, it

472

will not be invoked (even though it is connected to a signal which is

being emitted).

</para>

<para>

This completely optional filtering mechanism is mainly used as an optimization for signals

478

which are often emitted for many different reasons: the clients can filter out which events they are

479

interested in before the closure's marshalling code runs. For example, this is used extensively

480

		by the <link linkend="GObject-notify"><structfield>notify</structfield></link> signal of GObject: whenever a property is modified on a GObject,

481

instead of just emitting the <emphasis>notify</emphasis> signal, GObject associates as a detail to this

482

signal emission the name of the property modified. This allows clients who wish to be notified of changes

483

to only one property to filter most events before receiving them.

</para>

<para>

As a simple rule, users can and should set the detail parameter to zero: this will disable completely

488

this optional filtering for that signal.

</para>

</sect2>

</sect1>

</chapter>

nexmon – Blame information for rev 1