/+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 16:03:20 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210913160320-7ea8b6t006zr2879
* moved the path array out of the function call.

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
 
 */
20
 
[CCode (cheader_filename = "gjs/gjs.h",
21
 
        cprefix = "Gjs",
22
 
        lower_case_cprefix = "gjs_")]
 
7
[CCode (cheader_filename = "gjs/gjs.h", cprefix = "Gjs", lower_case_cprefix = "gjs_")]
23
8
namespace Gjs {
24
9
  
25
10
  
26
 
  [CCode (cname = "GjsError", 
27
 
          cprefix = "GJS_ERROR_",
28
 
          lower_case_cprefix = "gjs_error_")]
29
 
  public errordomain Error {
 
11
  [CCode (cname = "GjsError", cprefix = "GJS_ERROR_", lower_case_cprefix = "gjs_error_")]
 
12
  public errordomain GjsError {
30
13
    FAILED,
31
14
    EXIT,
32
15
  }
33
16
  
34
 
  [CCode (cname = "GjsJSError",
35
 
          cprefix = "GJS_JS_ERROR_",
36
 
          lower_case_cprefix = "gjs_js_error_")]
37
 
  public errordomain JSError {
 
17
  [CCode (cname = "GjsJSError", cprefix = "GJS_JS_ERROR_", lower_case_cprefix = "gjs_js_error_")]
 
18
  public errordomain GjsJSError {
38
19
    ERROR,
39
20
    EVAL_ERROR,
40
21
    INTERNAL_ERROR,
46
27
    URI_ERROR,
47
28
  }
48
29
  
 
30
  /*
 
31
   * Gjs.Context is an opaque datastructure with no outward visible
 
32
   * members.
 
33
   */
49
34
  [CCode (cname = "GjsContext",
50
35
          type_id = "GJS_TYPE_CONTEXT")]
51
36
  public class Context : GLib.Object {
52
37
    
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
 
    
110
38
    [CCode (cname = "gjs_context_new")]
111
39
    public Context ();
112
40
    
113
41
    [CCode (cname = "gjs_context_new_with_search_path")]
114
 
    public Context.with_search_path ([CCode (array_length = false)]
115
 
                                     string[] search_path);
 
42
    public Context.with_search_path ([CCode (array_length = false)] string[] search_path);
116
43
    
117
44
    [CCode (cname = "gjs_context_eval_file")]
118
45
    public bool eval_file (string filename,
148
75
                                     throws GLib.Error;
149
76
    
150
77
    [CCode (cname = "gjs_context_set_argv")]
151
 
    public void set_argv ([CCode (array_length_pos = 0.1,
152
 
                                  type = "const char**")]
 
78
    public void set_argv ([CCode (array_length_pos = 0.1)]
153
79
                          string[] array_values);
154
80
    
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
 
     */
162
81
    [CCode (cname = "gjs_context_get_all")]
163
 
    public GLib.List<Context> get_all ();
 
82
    public GLib.List get_all ();
164
83
    
165
84
    [CCode (cname = "gjs_context_get_current")]
166
85
    public static Context get_current ();
168
87
    [CCode (cname = "gjs_context_make_current")]
169
88
    public void make_current ();
170
89
    
171
 
    /**
172
 
     * Returns a pointer to the underlying native context. For SpiderMonkey,
173
 
     * this is a JSContext *
174
 
     */
175
90
    [CCode (cname = "gjs_context_get_native_context")]
176
91
    public GLib.pointer get_native_context ();
177
92
    
178
93
    [CCode (cname = "gjs_context_print_stack_stderr")]
179
94
    public void print_stack_stderr ();
180
95
    
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
 
     */
199
96
    [CCode (cname = "gjs_context_maybe_gc")]
200
97
    public void maybe_gc ();
201
98
    
202
 
    /**
203
 
     * Initiate a full GC; may or may not block until complete. This
204
 
     * function just calls Spidermonkey JS_GC().
205
 
     */
206
99
    [CCode (cname = "gjs_context_gc")]
207
100
    public void gc ();
208
101
    
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
 
     */
216
102
    [CCode (cname = "gjs_context_get_profiler")]
217
103
    public Profiler get_profiler ();
218
104
    
 
105
    [CCode (cname = "gjs_profiler_chain_sgnal")]
 
106
    public bool profiler_chain_signal (Posix.siginfo_t info);
 
107
    
219
108
    [CCode (cname = "gjs_context_setup_debugger_console")]
220
109
    public void setup_debugger_console ();
221
110
  }
222
111
  
223
 
  [CCode (cheader_filename = "gjs/context.h",
224
 
          cname = "gjs_dumpstack")]
 
112
  [CCode (cheader_filename = "gjs/context.h", cname = "gjs_dump_stack")]
225
113
  public void dump_stack ();
226
114
  
227
 
  /**
228
 
   * Returns the underlying version of the JS engine.
229
 
   *
230
 
   * Returns: a string
231
 
   */
232
 
  [CCode (cheader_filename = "gjs/context.h",
233
 
          cname = "gjs_get_js_version")]
 
115
  [CCode (cheader_filename = "gjs/context.h", cname = "gjs_get_js_version")]
234
116
  public string get_js_version ();
235
117
  
236
118
  /*
237
119
   * This class has no visible _new function, can only be created from
238
120
   * context.
239
121
   */
240
 
  [CCode (cheader_filename = "gjs/profiler.h",
241
 
          cname = "GjsProfiler",
242
 
          type_id = "GJS_TYPE_PROFILER")]
 
122
  [CCode (cheader_filename = "gjs/profiler.h", cname = "GjsProfiler", type_id = "GJS_TYPE_PROFILER")]
243
123
  public class Profiler : GLib.Object {
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
 
     */
 
124
    
250
125
    [CCode (cname = "gjs_profiler_set_capture_writer")]
251
 
    public void set_capture_writer (GLib.pointer capture);
 
126
    void set_capture_writer (GLib.pointer capture);
252
127
    
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
 
     */
257
128
    [CCode (cname = "gjs_profiler_set_filename")]
258
 
    public void set_filename (string filename);
259
 
    
 
129
    void set_filename (string filename);
260
130
    
261
131
    [CCode (cname = "gjs_profiler_set_fd")]
262
 
    public void set_fd (int fd);
 
132
    void set_fd (int fd);
263
133
    
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
 
     */
278
134
    [CCode (cname = "gjs_profiler_start")]
279
 
    public void start ();
 
135
    void start ();
280
136
    
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
 
     */
292
137
    [CCode (cname = "gjs_profiler_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);
 
138
    void stop ();
308
139
  }
309
140
  
310
 
  [CCode (cheader_filename = "gjs/mem.h",
311
 
          cname = "gjs_memory_report")]
312
 
  public void memory_report (string where,
 
141
  [CCode (cheader_filename = "gjs/mem.h", cname = "gjs_memory_report")]
 
142
  void memory_report (string where,
313
143
                 bool die_if_fail);
314
144
  
315
 
  [CCode (cheader_filename = "gjs/coverage.h",
316
 
          cname = "GjsProfiler",
317
 
          type_id = "GJS_TYPE_COVERAGE")]
 
145
  [CCode (cheader_filename = "gjs/coverage.h", cname = "GjsProfiler", type_id = "GJS_TYPE_COVERAGE")]
318
146
  public class Coverage : GLib.Object {
319
147
    
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
 
     */
351
148
    [CCode (cname = "gjs_coverage_new")]
352
149
    public Coverage (string coverage_prefixes,
353
150
                     Context coverage_context,
354
151
                     GLib.File output_dir);
355
152
    
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
 
     */
367
153
    [CCode (cname = "gjs_coverage_write_statistics")]
368
154
    public void write_statistics ();
369
155
    
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
 
     */
374
156
    [CCode (cname = "gjs_coverage_enable")]
375
157
    public static void enable ();
376
158
  }