1/*
2 * Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 *
23 */
24
25#ifndef SHARE_JFR_METADATA_JFRSERIALIZER_HPP
26#define SHARE_JFR_METADATA_JFRSERIALIZER_HPP
27
28#include "memory/allocation.hpp"
29#include "jfr/recorder/checkpoint/jfrCheckpointWriter.hpp"
30#include "jfrfiles/jfrTypes.hpp"
31
32/*
33 * A "type" in Jfr is a binary relation defined by enumerating a set of <key, value> ordered pairs:
34 *
35 * { <1, myvalue>, <2, mysecondvalue>, ... }
36 *
37 * The key should be a type relative unique id. A value is an instance of the type.
38 *
39 * By defining and registering a type, keys can be written to event fields and the
40 * framework will maintain the mapping to the corresponding value (if you register as below).
41 *
42 * Inherit JfrSerializer, create a CHeapObj instance and then use JfrSerializer::register_serializer(...) to register.
43 * Once registered, the ownership of the serializer instance is transferred to Jfr.
44 *
45 * How to register:
46 *
47 * bool register_serializer(JfrTypeId id, bool require_safepoint, bool permit_cache, JfrSerializer* serializer)
48 *
49 * The type identifiers are machine generated into an enum located in jfrfiles/jfrTypes.hpp (included).
50 *
51 * enum JfrTypeId {
52 * ...
53 * TYPE_THREADGROUP,
54 * TYPE_CLASSLOADER,
55 * TYPE_METHOD,
56 * TYPE_SYMBOL,
57 * TYPE_THREADSTATE,
58 * TYPE_INFLATECAUSE,
59 * ...
60 *
61 * id this is the id of the type your are defining (see the enum above).
62 * require_safepoint indicate if your type need to be evaluated and serialized under a safepoint.
63 * permit_cache indicate if your type constants are stable to be cached.
64 * (implies the callback is invoked only once and the contents will be cached. Set this to true for static information).
65 * serializer the serializer instance.
66 *
67 * See below for guidance about how to implement serialize().
68 *
69 */
70class JfrSerializer : public CHeapObj<mtTracing> {
71 public:
72 virtual ~JfrSerializer() {}
73 static bool register_serializer(JfrTypeId id, bool require_safepoint, bool permit_cache, JfrSerializer* serializer);
74 virtual void serialize(JfrCheckpointWriter& writer) = 0;
75};
76
77/*
78 * Defining serialize(JfrCheckpointWriter& writer):
79 *
80 * Invoke writer.write_count(N) for the number of ordered pairs (cardinality) to be defined.
81 *
82 * You then write each individual ordered pair, <key, value> ...
83 *
84 * Here is a simple example, describing a type defining string constants:
85 *
86 * void MyType::serialize(JfrCheckpointWriter& writer) {
87 * const int nof_causes = ObjectSynchronizer::inflate_cause_nof;
88 * writer.write_count(nof_causes); // write number of ordered pairs (mappings) to follow
89 * for (int i = 0; i < nof_causes; i++) {
90 * writer.write_key(i); // write key
91 * writer.write(ObjectSynchronizer::inflate_cause_name((ObjectSynchronizer::InflateCause)i)); // write value
92 * }
93 * }
94 *
95 * Note that values can be complex, and can also referer to other types.
96 *
97 * Please see jfr/recorder/checkpoint/types/jfrType.cpp for reference.
98 */
99
100#endif // SHARE_JFR_METADATA_JFRSERIALIZER_HPP
101