/+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 vapi/gjs-1.0.vapi

  • Committer: Gustav Hartvigsson
  • Date: 2021-09-14 13:56:36 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210914135636-a8d6yrdmuh2cprxs
Reorganise files a bit.

Show diffs side-by-side

added added

removed removed

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