/+junk/gjs-vapi

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/%2Bjunk/gjs-vapi

« back to all changes in this revision

Viewing changes to gjs-1.0.vapi

  • Committer: Gustav Hartvigsson
  • Date: 2021-09-13 19:52:56 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210913195256-axsvp0cjbi32ups2
* Added comments to the VAPI file.

Show diffs side-by-side

added added

removed removed

Lines of Context:
gjs-1.0.vapi
4
4
 * SPDX-FileContributor: Authored By: Gustav Hartvigsson
5
5
 */
6
6
 
 
7
/*
 
8
 * All comments are copid from the GJS source code, but changed to work with
 
9
 * valadoc.
 
10
 */
 
11
 
 
12
/**
 
13
 * JavaScript bindings for GNOME
 
14
 *
 
15
 * Use the GNOME platform libraries in your JavaScript programs.
 
16
 * GJS powers GNOME Shell, Polari, GNOME Documents, and many other apps.
 
17
 * Under the hood it uses SpiderMonkey, Mozilla's JavaScript engine
 
18
 * originally developed for Firefox.
 
19
 */
7
20
[CCode (cheader_filename = "gjs/gjs.h",
8
21
        cprefix = "Gjs",
9
22
        lower_case_cprefix = "gjs_")]
33
46
    URI_ERROR,
34
47
  }
35
48
  
36
 
  /*
37
 
   * Gjs.Context is an opaque datastructure with no outward visible
38
 
   * members.
39
 
   */
40
49
  [CCode (cname = "GjsContext",
41
50
          type_id = "GJS_TYPE_CONTEXT")]
42
51
  public class Context : GLib.Object {
43
52
    
 
53
    /*
 
54
     * The properties here are based on what I can read from the C++ source
 
55
     * code.
 
56
     */
 
57
    
 
58
    /**
 
59
     * Path where modules to import should reside.
 
60
     */
 
61
    
 
62
    public string[] search_path {construct;}
 
63
    
 
64
    /**
 
65
     * The filename of the launched JS program
 
66
     */
 
67
    public string program_name {get {
 
68
      unowned string ret_val = null;
 
69
      this.@get ("program-name", ref ret_val);
 
70
      return ret_val;
 
71
    } construct;}
 
72
    
 
73
    /**
 
74
     * The full path of the launched file or NULL if GJS was launched from
 
75
     * the C API or interactive console.
 
76
     */
 
77
    public string program_path {get {
 
78
      unowned string ret_val = null;
 
79
      this.@get ("program-path", ref ret_val);
 
80
      return ret_val;
 
81
    } construct;}
 
82
    /**
 
83
     * Set this property to profile any JS code run by this context. By
 
84
     * default, the profiler is started and stopped when you call
 
85
     * {@link Gjs.Context.eval}.
 
86
     *
 
87
     * The value of this property is superseded by the GJS_ENABLE_PROFILER
 
88
     * environment variable.
 
89
     *
 
90
     * You may only have one context with the profiler enabled at a time.
 
91
     */
 
92
    [NoAccessorMethod]
 
93
    public bool profiler_enabled {construct;}
 
94
    
 
95
    /**
 
96
     * Set this property to install a SIGUSR2 signal handler that starts and
 
97
     * stops the profiler. This property also implies that
 
98
     * {@link Gjs.Context.profiler_enabled} is set.
 
99
     */
 
100
    [NoAccessorMethod]
 
101
    public bool profiler_sigusr2 {construct;}
 
102
    
 
103
    /**
 
104
     * Whether to execute the file as a module
 
105
     */
 
106
    [NoAccessorMethod]
 
107
    public bool exec_as_module {construct;}
 
108
    
 
109
    
44
110
    [CCode (cname = "gjs_context_new")]
45
111
    public Context ();
46
112
    
82
148
                                     throws GLib.Error;
83
149
    
84
150
    [CCode (cname = "gjs_context_set_argv")]
85
 
    public void set_argv ([CCode (array_length_pos = 0.1)]
 
151
    public void set_argv ([CCode (array_length_pos = 0.1,
 
152
                                  type = "const char**")]
86
153
                          string[] array_values);
87
154
    
 
155
    /**
 
156
     * Returns a newly-allocated list containing all known instances of 
 
157
     * {@link Gjs.Context}. This is useful for operating on the contexts from a
 
158
     * process-global situation such as a debugger.
 
159
     *
 
160
     * @return Known {@link Gjs.Context} instances
 
161
     */
88
162
    [CCode (cname = "gjs_context_get_all")]
89
 
    public GLib.List get_all ();
 
163
    public GLib.List<Context> get_all ();
90
164
    
91
165
    [CCode (cname = "gjs_context_get_current")]
92
166
    public static Context get_current ();
94
168
    [CCode (cname = "gjs_context_make_current")]
95
169
    public void make_current ();
96
170
    
 
171
    /**
 
172
     * Returns a pointer to the underlying native context. For SpiderMonkey,
 
173
     * this is a JSContext *
 
174
     */
97
175
    [CCode (cname = "gjs_context_get_native_context")]
98
176
    public GLib.pointer get_native_context ();
99
177
    
100
178
    [CCode (cname = "gjs_context_print_stack_stderr")]
101
179
    public void print_stack_stderr ();
102
180
    
 
181
    /**
 
182
     * Similar to the Spidermonkey JS_MaybeGC() call which
 
183
     * heuristically looks at JS runtime memory usage and
 
184
     * may initiate a garbage collection.
 
185
     *
 
186
     * This function always unconditionally invokes JS_MaybeGC(), but
 
187
     * additionally looks at memory usage from the system malloc()
 
188
     * when available, and if the delta has grown since the last run
 
189
     * significantly, also initiates a full JavaScript garbage
 
190
     * collection.  The idea is that since GJS is a bridge between
 
191
     * JavaScript and system libraries, and JS objects act as proxies
 
192
     * for these system memory objects, GJS consumers need a way to
 
193
     * hint to the runtime that it may be a good idea to try a
 
194
     * collection.
 
195
     *
 
196
     * A good time to call this function is when your application
 
197
     * transitions to an idle state.
 
198
     */
103
199
    [CCode (cname = "gjs_context_maybe_gc")]
104
200
    public void maybe_gc ();
105
201
    
 
202
    /**
 
203
     * Initiate a full GC; may or may not block until complete. This
 
204
     * function just calls Spidermonkey JS_GC().
 
205
     */
106
206
    [CCode (cname = "gjs_context_gc")]
107
207
    public void gc ();
108
208
    
 
209
    /*
 
210
     * Returns the profiler's internal instance of {@link Gjs.Profiler}
 
211
     * for you to customize, or %NULL if profiling is not enabled on this
 
212
     * {@link Gjs.Context}.
 
213
     *
 
214
     * @returns {@link Gjs.Profiler}
 
215
     */
109
216
    [CCode (cname = "gjs_context_get_profiler")]
110
217
    public Profiler get_profiler ();
111
218
    
112
 
    [CCode (cname = "gjs_profiler_chain_sgnal")]
113
 
    public bool profiler_chain_signal (Posix.siginfo_t info);
114
 
    
115
219
    [CCode (cname = "gjs_context_setup_debugger_console")]
116
220
    public void setup_debugger_console ();
117
221
  }
118
222
  
119
223
  [CCode (cheader_filename = "gjs/context.h",
120
 
          cname = "gjs_dump_stack")]
 
224
          cname = "gjs_dumpstack")]
121
225
  public void dump_stack ();
122
226
  
 
227
  /**
 
228
   * Returns the underlying version of the JS engine.
 
229
   *
 
230
   * Returns: a string
 
231
   */
123
232
  [CCode (cheader_filename = "gjs/context.h",
124
233
          cname = "gjs_get_js_version")]
125
234
  public string get_js_version ();
132
241
          cname = "GjsProfiler",
133
242
          type_id = "GJS_TYPE_PROFILER")]
134
243
  public class Profiler : GLib.Object {
135
 
    
 
244
    /**
 
245
     * Set the capture writer to which profiling data is written when the
 
246
     * ''this'' is stopped.
 
247
     * 
 
248
     * @param capture A {SysprofCaptureWriter}
 
249
     */
136
250
    [CCode (cname = "gjs_profiler_set_capture_writer")]
137
 
    void set_capture_writer (GLib.pointer capture);
 
251
    public void set_capture_writer (GLib.pointer capture);
138
252
    
 
253
    /**
 
254
     * Set the file to which profiling data is written when the ''this'' is
 
255
     * stopped. By default, this is `gjs-$PID.syscap` in the current directory.
 
256
     */
139
257
    [CCode (cname = "gjs_profiler_set_filename")]
140
 
    void set_filename (string filename);
 
258
    public void set_filename (string filename);
 
259
    
141
260
    
142
261
    [CCode (cname = "gjs_profiler_set_fd")]
143
 
    void set_fd (int fd);
 
262
    public void set_fd (int fd);
144
263
    
 
264
    /**
 
265
     * As expected, this starts the {@link Gjs.Profiler}.
 
266
     *
 
267
     * This will enable the underlying JS profiler and register a POSIX timer to
 
268
     * deliver SIGPROF on the configured sampling frequency.
 
269
     *
 
270
     * To reduce sampling overhead, Gjs.Profiler stashes information
 
271
     * about the profile to be calculated once the profiler has been disabled.
 
272
     * Calling Gjs.Profiler.stop() will result in that delayed work to be
 
273
     * completed.
 
274
     *
 
275
     * You should call Gjs.Profiler.stop() when the profiler is no longer
 
276
     * needed.
 
277
     */
145
278
    [CCode (cname = "gjs_profiler_start")]
146
 
    void start ();
 
279
    public void start ();
147
280
    
 
281
    /**
 
282
     * Stops a currently running {@link Gjs.Profiler}. If the profiler is not 
 
283
     * running, this function will do nothing.
 
284
     *
 
285
     * Some work may be delayed until the end of the capture. Such delayed work
 
286
     * includes flushing the resulting samples and file location information to
 
287
     * disk.
 
288
     *
 
289
     * This may block while writing to disk. Generally, the writes are delivered
 
290
     * to a tmpfs device, and are therefore negligible.
 
291
     */
148
292
    [CCode (cname = "gjs_profiler_stop")]
149
 
    void stop ();
 
293
    public void stop ();
 
294
    
 
295
    /**
 
296
     * Use this to pass a signal info caught by another signal handler to a
 
297
     * {@link Gjs.Profiler}. This might be needed if you have your own complex
 
298
     * signal handling system for which Gjs.Profiler cannot simply add a SIGUSR2
 
299
     * handler.
 
300
     *
 
301
     * This function should only be called from the JS thread.
 
302
     *
 
303
     * @return true if the signal was handled.
 
304
     */
 
305
    [CCode (cname = "gjs_profiler_chain_signal")]
 
306
    public static bool chain_signal (Context ctx,
 
307
                                     Posix.siginfo_t info);
150
308
  }
151
309
  
152
310
  [CCode (cheader_filename = "gjs/mem.h",
153
311
          cname = "gjs_memory_report")]
154
 
  void memory_report (string where,
 
312
  public void memory_report (string where,
155
313
                 bool die_if_fail);
156
314
  
157
315
  [CCode (cheader_filename = "gjs/coverage.h",
159
317
          type_id = "GJS_TYPE_COVERAGE")]
160
318
  public class Coverage : GLib.Object {
161
319
    
 
320
    /**
 
321
     * Prefixes of files on which to perform coverage analysis
 
322
     */
 
323
    public string prefixes {construct;}
 
324
    
 
325
    /**
 
326
     * A context to gather coverage stats for
 
327
     */
 
328
    public Context context {construct;}
 
329
    
 
330
    /**
 
331
     * Directory handle at which to output coverage statistics
 
332
     */
 
333
    public GLib.File output_directory {construct;}
 
334
    
 
335
    /**
 
336
     * Creates a new {@link Gjs.Coverage} object that collects coverage
 
337
     * information for any scripts run in context.
 
338
     *
 
339
     * Scripts which were provided as part of {@link prefixes} will be written
 
340
     * out to {@link output_dir}, in the same directory structure relative to
 
341
     * the source dir where the tests were run.
 
342
     *
 
343
     * @param coverage_prefixes A null-terminated strv of prefixes of files on
 
344
     * which to record code coverage
 
345
     *
 
346
     * @param coverage_context A {@link Gjs.Context} object
 
347
     *
 
348
     * @param output_dir A {@link GLib.File} handle to a directory in which to
 
349
     * write coverage information
 
350
     */
162
351
    [CCode (cname = "gjs_coverage_new")]
163
352
    public Coverage (string coverage_prefixes,
164
353
                     Context coverage_context,
165
354
                     GLib.File output_dir);
166
355
    
 
356
    /**
 
357
     * Scripts which were provided as part of the {@link Gjs.Coverage.prefixes}
 
358
     * construction property will be written out to {output_directory}, in the
 
359
     * same directory structure relative to the source dir where the tests were
 
360
     * run.
 
361
     *
 
362
     * This function takes all available statistics and writes them out to
 
363
     * either the file provided or to files of the pattern (filename).info in
 
364
     * the same directory as the scanned files. It will provide coverage data
 
365
     * for all files ending with ".js" in the coverage directories.
 
366
     */
167
367
    [CCode (cname = "gjs_coverage_write_statistics")]
168
368
    public void write_statistics ();
169
369
    
 
370
    /**
 
371
     * This function must be called before creating any {@link Gjs.Context}, 
 
372
     * if you intend to use any {@link Gjs.Coverage} APIs.
 
373
     */
170
374
    [CCode (cname = "gjs_coverage_enable")]
171
375
    public static void enable ();
172
376
  }