[chromium] Implement TRACE_EVENT macros for sampling profiling
[WebKit-https.git] / Source / Platform / chromium / public / Platform.h
1 /*
2  * Copyright (C) 2012 Google Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  *     * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *     * Redistributions in binary form must reproduce the above
11  * copyright notice, this list of conditions and the following disclaimer
12  * in the documentation and/or other materials provided with the
13  * distribution.
14  *     * Neither the name of Google Inc. nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31 #ifndef Platform_h
32 #define Platform_h
33
34 #ifdef WIN32
35 #include <windows.h>
36 #endif
37
38 #include "WebAudioDevice.h"
39 #include "WebCommon.h"
40 #include "WebData.h"
41 #include "WebGamepads.h"
42 #include "WebGraphicsContext3D.h"
43 #include "WebLocalizedString.h"
44 #include "WebString.h"
45 #include "WebVector.h"
46
47 class GrContext;
48
49 namespace WebKit {
50
51 class WebAudioBus;
52 class WebBlobRegistry;
53 class WebClipboard;
54 class WebCompositorSupport;
55 class WebCookieJar;
56 class WebDiscardableMemory;
57 class WebFileSystem;
58 class WebFileUtilities;
59 class WebFlingAnimator;
60 class WebGestureCurveTarget;
61 class WebGestureCurve;
62 class WebHyphenator;
63 class WebMediaStreamCenter;
64 class WebMediaStreamCenterClient;
65 class WebMessagePortChannel;
66 class WebMimeRegistry;
67 class WebPluginListBuilder;
68 class WebRTCPeerConnectionHandler;
69 class WebRTCPeerConnectionHandlerClient;
70 class WebSandboxSupport;
71 class WebSocketStreamHandle;
72 class WebStorageNamespace;
73 class WebUnitTestSupport;
74 class WebThemeEngine;
75 class WebThread;
76 class WebURL;
77 class WebURLLoader;
78 class WebWorkerRunLoop;
79 struct WebFloatPoint;
80 struct WebLocalizedString;
81 struct WebSize;
82
83 class Platform {
84 public:
85     // HTML5 Database ------------------------------------------------------
86
87 #ifdef WIN32
88     typedef HANDLE FileHandle;
89 #else
90     typedef int FileHandle;
91 #endif
92
93     WEBKIT_EXPORT static void initialize(Platform*);
94     WEBKIT_EXPORT static void shutdown();
95     WEBKIT_EXPORT static Platform* current();
96
97     // May return null.
98     virtual WebCookieJar* cookieJar() { return 0; }
99
100     // Must return non-null.
101     virtual WebClipboard* clipboard() { return 0; }
102
103     // Must return non-null.
104     virtual WebFileUtilities* fileUtilities() { return 0; }
105
106     // Must return non-null.
107     virtual WebMimeRegistry* mimeRegistry() { return 0; }
108
109     // May return null if sandbox support is not necessary
110     virtual WebSandboxSupport* sandboxSupport() { return 0; }
111
112     // May return null on some platforms.
113     virtual WebThemeEngine* themeEngine() { return 0; }
114
115     // Must return non-null.
116     virtual WebHyphenator* hyphenator() { return 0; }
117
118
119     // Audio --------------------------------------------------------------
120
121     virtual double audioHardwareSampleRate() { return 0; }
122     virtual size_t audioHardwareBufferSize() { return 0; }
123
124     // Creates a device for audio I/O.
125     // Pass in (numberOfInputChannels > 0) if live/local audio input is desired.
126     virtual WebAudioDevice* createAudioDevice(size_t bufferSize, unsigned numberOfInputChannels, unsigned numberOfChannels, double sampleRate, WebAudioDevice::RenderCallback*, const WebString& deviceId) { return 0; }
127
128     // FIXME: remove deprecated APIs once chromium switches over to new method.
129     virtual WebAudioDevice* createAudioDevice(size_t bufferSize, unsigned numberOfChannels, double sampleRate, WebAudioDevice::RenderCallback*) { return 0; }
130     virtual WebAudioDevice* createAudioDevice(size_t bufferSize, unsigned numberOfInputChannels, unsigned numberOfChannels, double sampleRate, WebAudioDevice::RenderCallback*) { return 0; }
131
132
133     // Blob ----------------------------------------------------------------
134
135     // Must return non-null.
136     virtual WebBlobRegistry* blobRegistry() { return 0; }
137
138
139     // Database ------------------------------------------------------------
140
141     // Opens a database file; dirHandle should be 0 if the caller does not need
142     // a handle to the directory containing this file
143     virtual FileHandle databaseOpenFile(const WebString& vfsFileName, int desiredFlags) { return FileHandle(); }
144
145     // Deletes a database file and returns the error code
146     virtual int databaseDeleteFile(const WebString& vfsFileName, bool syncDir) { return 0; }
147
148     // Returns the attributes of the given database file
149     virtual long databaseGetFileAttributes(const WebString& vfsFileName) { return 0; }
150
151     // Returns the size of the given database file
152     virtual long long databaseGetFileSize(const WebString& vfsFileName) { return 0; }
153
154     // Returns the space available for the given origin
155     virtual long long databaseGetSpaceAvailableForOrigin(const WebKit::WebString& originIdentifier) { return 0; }
156
157
158     // DOM Storage --------------------------------------------------
159
160     // Return a LocalStorage namespace that corresponds to the following path.
161     virtual WebStorageNamespace* createLocalStorageNamespace(const WebString& path, unsigned quota) { return 0; }
162
163
164     // FileSystem ----------------------------------------------------------
165
166     // Must return non-null.
167     virtual WebFileSystem* fileSystem() { return 0; }
168
169
170     // Gamepad -------------------------------------------------------------
171
172     virtual void sampleGamepads(WebGamepads& into) { into.length = 0; }
173
174
175     // History -------------------------------------------------------------
176
177     // Returns the hash for the given canonicalized URL for use in visited
178     // link coloring.
179     virtual unsigned long long visitedLinkHash(
180         const char* canonicalURL, size_t length) { return 0; }
181
182     // Returns whether the given link hash is in the user's history. The
183     // hash must have been generated by calling VisitedLinkHash().
184     virtual bool isLinkVisited(unsigned long long linkHash) { return false; }
185
186
187     // Keygen --------------------------------------------------------------
188
189     // Handle the <keygen> tag for generating client certificates
190     // Returns a base64 encoded signed copy of a public key from a newly
191     // generated key pair and the supplied challenge string. keySizeindex
192     // specifies the strength of the key.
193     virtual WebString signedPublicKeyAndChallengeString(unsigned keySizeIndex,
194                                                         const WebString& challenge,
195                                                         const WebURL& url) { return WebString(); }
196
197
198     // Memory --------------------------------------------------------------
199
200     // Returns the current space allocated for the pagefile, in MB.
201     // That is committed size for Windows and virtual memory size for POSIX
202     virtual size_t memoryUsageMB() { return 0; }
203
204     // Same as above, but always returns actual value, without any caches.
205     virtual size_t actualMemoryUsageMB() { return 0; }
206
207     // If memory usage is below this threshold, do not bother forcing GC.
208     virtual size_t lowMemoryUsageMB() { return 256; }
209
210     // If memory usage is above this threshold, force GC more aggressively.
211     virtual size_t highMemoryUsageMB() { return 1024; }
212
213     // Delta of memory usage growth (vs. last actualMemoryUsageMB()) to force GC when memory usage is high.
214     virtual size_t highUsageDeltaMB() { return 128; }
215
216     // Returns private and shared usage, in bytes. Private bytes is the amount of
217     // memory currently allocated to this process that cannot be shared. Returns
218     // false on platform specific error conditions.
219     virtual bool processMemorySizesInBytes(size_t* privateBytes, size_t* sharedBytes) { return false; }
220
221     // A callback interface for requestProcessMemorySizes
222     class ProcessMemorySizesCallback {
223     public:
224         virtual ~ProcessMemorySizesCallback() { }
225         virtual void dataReceived(size_t privateBytes, size_t sharedBytes) = 0;
226     };
227
228     // Requests private and shared usage, in bytes. Private bytes is the amount of
229     // memory currently allocated to this process that cannot be shared.
230     // The callback ownership is passed to the callee.
231     virtual void requestProcessMemorySizes(ProcessMemorySizesCallback* requestCallback) { }
232
233     // Reports number of bytes used by memory allocator for internal needs.
234     // Returns true if the size has been reported, or false otherwise.
235     virtual bool memoryAllocatorWasteInBytes(size_t*) { return false; }
236
237     // Allocates discardable memory. May return 0, even if the platform supports
238     // discardable memory. If nonzero, however, then the WebDiscardableMmeory is
239     // returned in an locked state. You may use its underlying data() member
240     // directly, taking care to unlock it when you are ready to let it become
241     // discardable.
242     virtual WebDiscardableMemory* allocateAndLockDiscardableMemory(size_t bytes) { return 0; }
243
244
245     // Message Ports -------------------------------------------------------
246
247     // Creates a Message Port Channel. This can be called on any thread.
248     // The returned object should only be used on the thread it was created on.
249     virtual WebMessagePortChannel* createMessagePortChannel() { return 0; }
250
251
252     // Network -------------------------------------------------------------
253
254     // Returns a new WebURLLoader instance.
255     virtual WebURLLoader* createURLLoader() { return 0; }
256
257     // A suggestion to prefetch IP information for the given hostname.
258     virtual void prefetchHostName(const WebString&) { }
259
260     // Returns a new WebSocketStreamHandle instance.
261     virtual WebSocketStreamHandle* createSocketStreamHandle() { return 0; }
262
263     // Returns the User-Agent string that should be used for the given URL.
264     virtual WebString userAgent(const WebURL&) { return WebString(); }
265
266     // A suggestion to cache this metadata in association with this URL.
267     virtual void cacheMetadata(const WebURL&, double responseTime, const char* data, size_t dataSize) { }
268
269
270     // Plugins -------------------------------------------------------------
271
272     // If refresh is true, then cached information should not be used to
273     // satisfy this call.
274     virtual void getPluginList(bool refresh, WebPluginListBuilder*) { }
275
276
277     // Resources -----------------------------------------------------------
278
279     // Returns a localized string resource (with substitution parameters).
280     virtual WebString queryLocalizedString(WebLocalizedString::Name) { return WebString(); }
281     virtual WebString queryLocalizedString(WebLocalizedString::Name, const WebString& parameter) { return WebString(); }
282     virtual WebString queryLocalizedString(WebLocalizedString::Name, const WebString& parameter1, const WebString& parameter2) { return WebString(); }
283
284
285     // Threads -------------------------------------------------------
286
287     // Creates an embedder-defined thread.
288     virtual WebThread* createThread(const char* name) { return 0; }
289
290     // Returns an interface to the current thread. This is owned by the
291     // embedder.
292     virtual WebThread* currentThread() { return 0; }
293
294
295     // Profiling -----------------------------------------------------------
296
297     virtual void decrementStatsCounter(const char* name) { }
298     virtual void incrementStatsCounter(const char* name) { }
299
300
301     // Resources -----------------------------------------------------------
302
303     // Returns a blob of data corresponding to the named resource.
304     virtual WebData loadResource(const char* name) { return WebData(); }
305
306     // Decodes the in-memory audio file data and returns the linear PCM audio data in the destinationBus.
307     // A sample-rate conversion to sampleRate will occur if the file data is at a different sample-rate.
308     // Returns true on success.
309     virtual bool loadAudioResource(WebAudioBus* destinationBus, const char* audioFileData, size_t dataSize, double sampleRate) { return false; }
310
311
312     // Sandbox ------------------------------------------------------------
313
314     // In some browsers, a "sandbox" restricts what operations a program
315     // is allowed to preform. Such operations are typically abstracted out
316     // via this API, but sometimes (like in HTML 5 database opening) WebKit
317     // needs to behave differently based on whether it's restricted or not.
318     // In these cases (and these cases only) you can call this function.
319     // It's OK for this value to be conservitive (i.e. true even if the
320     // sandbox isn't active).
321     virtual bool sandboxEnabled() { return false; }
322
323
324     // Screen -------------------------------------------------------------
325
326     // Supplies the system monitor color profile.
327     virtual void screenColorProfile(WebVector<char>* profile) { }
328
329
330     // Sudden Termination --------------------------------------------------
331
332     // Disable/Enable sudden termination.
333     virtual void suddenTerminationChanged(bool enabled) { }
334
335
336     // System --------------------------------------------------------------
337
338     // Returns a value such as "en-US".
339     virtual WebString defaultLocale() { return WebString(); }
340
341     // Wall clock time in seconds since the epoch.
342     virtual double currentTime() { return 0; }
343
344     // Monotonically increasing time in seconds from an arbitrary fixed point in the past.
345     // This function is expected to return at least millisecond-precision values. For this reason,
346     // it is recommended that the fixed point be no further in the past than the epoch.
347     virtual double monotonicallyIncreasingTime() { return 0; }
348
349     // WebKit clients must implement this funcion if they use cryptographic randomness.
350     virtual void cryptographicallyRandomValues(unsigned char* buffer, size_t length) = 0;
351
352     // Delayed work is driven by a shared timer.
353     typedef void (*SharedTimerFunction)();
354     virtual void setSharedTimerFiredFunction(SharedTimerFunction timerFunction) { }
355     virtual void setSharedTimerFireInterval(double) { }
356     virtual void stopSharedTimer() { }
357
358     // Callable from a background WebKit thread.
359     virtual void callOnMainThread(void (*func)(void*), void* context) { }
360
361
362     // Testing -------------------------------------------------------------
363
364 #define HAVE_WEBUNITTESTSUPPORT 1
365     // Get a pointer to testing support interfaces. Will not be available in production builds.
366     virtual WebUnitTestSupport* unitTestSupport() { return 0; }
367
368
369     // Tracing -------------------------------------------------------------
370
371     // Get a pointer to the enabled state of the given trace category. The
372     // embedder can dynamically change the enabled state as trace event
373     // recording is started and stopped by the application. Only long-lived
374     // literal strings should be given as the category name. The implementation
375     // expects the returned pointer to be held permanently in a local static. If
376     // the unsigned char is non-zero, tracing is enabled. If tracing is enabled,
377     // addTraceEvent is expected to be called by the trace event macros.
378     virtual const unsigned char* getTraceCategoryEnabledFlag(const char* categoryName) { return 0; }
379
380     typedef long int TraceEventAPIAtomicWord;
381
382     // Get a pointer to a global state of the given thread. An embedder is
383     // expected to update the global state as the state of the embedder changes.
384     // A sampling thread in the Chromium side reads the global state periodically
385     // and reflects the sampling profiled results into about:tracing.
386     virtual TraceEventAPIAtomicWord* getTraceSamplingState(const unsigned bucketName) { return 0; }
387
388     // Add a trace event to the platform tracing system. Depending on the actual
389     // enabled state, this event may be recorded or dropped. 
390     // - phase specifies the type of event:
391     //   - BEGIN ('B'): Marks the beginning of a scoped event.
392     //   - END ('E'): Marks the end of a scoped event.
393     //   - INSTANT ('I'): Standalone, instantaneous event.
394     //   - START ('S'): Marks the beginning of an asynchronous event (the end
395     //     event can occur in a different scope or thread). The id parameter is
396     //     used to match START/FINISH pairs.
397     //   - FINISH ('F'): Marks the end of an asynchronous event.
398     //   - COUNTER ('C'): Used to trace integer quantities that change over
399     //     time. The argument values are expected to be of type int.
400     //   - METADATA ('M'): Reserved for internal use.
401     // - categoryEnabled is the pointer returned by getTraceCategoryEnabledFlag.
402     // - name is the name of the event. Also used to match BEGIN/END and
403     //   START/FINISH pairs.
404     // - id optionally allows events of the same name to be distinguished from
405     //   each other. For example, to trace the consutruction and destruction of
406     //   objects, specify the pointer as the id parameter.
407     // - numArgs specifies the number of elements in argNames, argTypes, and
408     //   argValues.
409     // - argNames is the array of argument names. Use long-lived literal strings
410     //   or specify the COPY flag.
411     // - argTypes is the array of argument types:
412     //   - BOOL (1): bool
413     //   - UINT (2): unsigned long long
414     //   - INT (3): long long
415     //   - DOUBLE (4): double
416     //   - POINTER (5): void*
417     //   - STRING (6): char* (long-lived null-terminated char* string)
418     //   - COPY_STRING (7): char* (temporary null-terminated char* string)
419     // - argValues is the array of argument values. Each value is the unsigned
420     //   long long member of a union of all supported types.
421     // - thresholdBeginId optionally specifies the value returned by a previous
422     //   call to addTraceEvent with a BEGIN phase.
423     // - threshold is used on an END phase event in conjunction with the
424     //   thresholdBeginId of a prior BEGIN event. The threshold is the minimum
425     //   number of microseconds that must have passed since the BEGIN event. If
426     //   less than threshold microseconds has passed, the BEGIN/END pair is
427     //   dropped.
428     // - flags can be 0 or one or more of the following, ORed together:
429     //   - COPY (0x1): treat all strings (name, argNames and argValues of type
430     //     string) as temporary so that they will be copied by addTraceEvent.
431     //   - HAS_ID (0x2): use the id argument to uniquely identify the event for
432     //     matching with other events of the same name.
433     //   - MANGLE_ID (0x4): specify this flag if the id parameter is the value
434     //     of a pointer.
435     virtual void addTraceEvent(
436         char phase,
437         const unsigned char* categoryEnabledFlag,
438         const char* name,
439         unsigned long long id,
440         int numArgs,
441         const char** argNames,
442         const unsigned char* argTypes,
443         const unsigned long long* argValues,
444         unsigned char flags) { }
445
446     // Callbacks for reporting histogram data.
447     // CustomCounts histogram has exponential bucket sizes, so that min=1, max=1000000, bucketCount=50 would do.
448     virtual void histogramCustomCounts(const char* name, int sample, int min, int max, int bucketCount) { }
449     // Enumeration histogram buckets are linear, boundaryValue should be larger than any possible sample value.
450     virtual void histogramEnumeration(const char* name, int sample, int boundaryValue) { }
451
452
453     // GPU ----------------------------------------------------------------
454     //
455     // May return null if GPU is not supported.
456     // Returns newly allocated and initialized offscreen WebGraphicsContext3D instance.
457     virtual WebGraphicsContext3D* createOffscreenGraphicsContext3D(const WebGraphicsContext3D::Attributes&) { return 0; }
458
459     // May return null if GPU is not supported.
460     // Returns the shared WebGraphicsContext3D. This is a singleton object for
461     // the entire process. Calling this function may destroy both the shared
462     // offscreen WebGraphicsContext3D and GrContext pointers last returned, so
463     // it should only be called from a single site. The implementor should
464     // create a new context before destroying its current context, if required,
465     // to ensure the same pointer can not be returned twice in a row for two
466     // different contexts.
467     virtual WebGraphicsContext3D* sharedOffscreenGraphicsContext3D() { return 0; }
468
469     // May return null if GPU is not supported.
470     // Returns the shared GrContext. This is a singleton object for the entire process.
471     virtual GrContext* sharedOffscreenGrContext() { return 0; }
472
473     // Returns true if the platform is capable of producing an offscreen context suitable for accelerating 2d canvas.
474     // This will return false if the platform cannot promise that contexts will be preserved across operations like
475     // locking the screen or if the platform cannot provide a context with suitable performance characteristics.
476     //
477     // This value must be checked again after a context loss event as the platform's capabilities may have changed.
478     virtual bool canAccelerate2dCanvas() { return false; }
479
480     virtual WebCompositorSupport* compositorSupport() { return 0; }
481
482     virtual WebFlingAnimator* createFlingAnimator() { return 0; }
483
484     // Creates a new fling animation curve instance for device |deviceSource|
485     // with |velocity| and already scrolled |cumulativeScroll| pixels.
486     virtual WebGestureCurve* createFlingAnimationCurve(int deviceSource, const WebFloatPoint& velocity, const WebSize& cumulativeScroll) { return 0; }
487
488     // WebRTC ----------------------------------------------------------
489
490     // Creates an WebRTCPeerConnectionHandler for RTCPeerConnection.
491     // May return null if WebRTC functionality is not avaliable or out of resources.
492     virtual WebRTCPeerConnectionHandler* createRTCPeerConnectionHandler(WebRTCPeerConnectionHandlerClient*) { return 0; }
493
494     // May return null if WebRTC functionality is not avaliable or out of resources.
495     virtual WebMediaStreamCenter* createMediaStreamCenter(WebMediaStreamCenterClient*) { return 0; }
496
497
498     // WebWorker ----------------------------------------------------------
499
500     virtual void didStartWorkerRunLoop(const WebWorkerRunLoop&) { }
501     virtual void didStopWorkerRunLoop(const WebWorkerRunLoop&) { }
502
503 protected:
504     virtual ~Platform() { }
505 };
506
507 } // namespace WebKit
508
509 #endif