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_VM_JFR_METADATA_JFRCONSTANTSERIALIZER_HPP
  26 #define SHARE_VM_JFR_METADATA_JFRCONSTANTSERIALIZER_HPP
  27 
  28 #include "memory/allocation.hpp"
  29 #include "jfr/recorder/checkpoint/jfrCheckpointWriter.hpp"
  30 #include "tracefiles/traceTypes.hpp"
  31 
  32 /*
  33  * A JfrConstant (type) is a relation defined by enumerating a set of <key, value> ordered pairs:
  34  *
  35  * { <1, "my_first_constant">, <2, "my_second_constant">, ... }
  36  *
  37  * Write the key into event fields and the framework will maintain the mapping (if you register as below).
  38  *
  39  * In order to support mapping of constants, we use an interface called JfrConstantSerializer.
  40  * Inherit JfrConstantSerializer, create a CHeapObj instance and use JfrConstantSerializer::register_serializer(...) to register.
  41  * Once registered, the ownership of the serializer instance is transferred to Jfr.
  42  *
  43  * How to register:
  44  *
  45  * bool register_serializer(JfrConstantTypeId id, bool require_safepoint, bool permit_cache, JfrConstantSerializer* serializer)
  46  *
  47  * The constant types are machine generated into an enum located in tracefiles/traceTypes.hpp (included).
  48  *
  49  *  enum JfrConstantTypeId {
  50  *    ...
  51  *    CONSTANT_TYPE_THREADGROUP,
  52  *    CONSTANT_TYPE_CLASSLOADER,
  53  *    CONSTANT_TYPE_METHOD,
  54  *    CONSTANT_TYPE_SYMBOL,
  55  *    CONSTANT_TYPE_THREADSTATE,
  56  *    CONSTANT_TYPE_INFLATECAUSE,
  57  *    ...
  58  *
  59  * id                 this is the id of the constant type your are defining (see the enum above).
  60  * require_safepoint  indicate if your constants need to be evaluated and written under a safepoint.
  61  * permit_cache       indicate if your constants are stable to be cached.
  62  *                    (implies the callback is invoked only once and the contents will be cached. Set this to true for static information).
  63  * serializer         the serializer instance you define.
  64  *
  65  * See below for guidance about how to implement write_constants().
  66  *
  67  */
  68 class JfrConstantSerializer : public CHeapObj<mtTracing> {
  69  public:
  70   virtual void write_constants(JfrCheckpointWriter& writer) = 0;
  71   virtual ~JfrConstantSerializer() {}
  72   static bool register_serializer(JfrConstantTypeId id, bool require_safepoint, bool permit_cache, JfrConstantSerializer* serializer);
  73 };
  74 
  75 /*
  76  *  Invoke writer.write_number_of_constants(num) to define the total number of constant mappings.
  77  *
  78  *  You then write the individual constants as ordered pairs, <key, value> ...
  79  *
  80  *  Here is an example:
  81  *
  82  *  void MyConstant::write_constants(JfrCheckpointWriter& writer) {
  83  *    const int nof_causes = ObjectSynchronizer::inflate_cause_nof;
  84  *    writer.write_number_of_constants(nof_causes);             // write number of constant (mappings) to follow
  85  *    for (int i = 0; i < nof_causes; i++) {
  86  *      writer.write_key(i);                                    // write key
  87  *      writer.write(ObjectSynchronizer::inflate_cause_name((ObjectSynchronizer::InflateCause)i)); // write value
  88  *    }
  89  *  }
  90  *
  91  * Please see jfr/recorder/checkpoint/constant/jfrConstant.cpp for reference.
  92  */
  93 
  94 #endif // SHARE_VM_JFR_METADATA_JFRCONSTANTSERIALIZER_HPP