Home | History | Annotate | Line # | Download | only in common 
      1 /*
      2  * Copyright (c) Meta Platforms, Inc. and affiliates.
      3  * All rights reserved.
      4  *
      5  * This source code is licensed under both the BSD-style license (found in the
      6  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
      7  * in the COPYING file in the root directory of this source tree).
      8  * You may select, at your option, one of the above-listed licenses.
      9  */
     10 
     11 #ifndef ZSTD_TRACE_H
     12 #define ZSTD_TRACE_H
     13 
     14 #include <stddef.h>
     15 
     16 /* weak symbol support
     17  * For now, enable conservatively:
     18  * - Only GNUC
     19  * - Only ELF
     20  * - Only x86-64, i386, aarch64 and risc-v.
     21  * Also, explicitly disable on platforms known not to work so they aren't
     22  * forgotten in the future.
     23  */
     24 #if !defined(ZSTD_HAVE_WEAK_SYMBOLS) && \
     25     defined(__GNUC__) && defined(__ELF__) && \
     26     (defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || \
     27      defined(_M_IX86) || defined(__aarch64__) || defined(__riscv)) && \
     28     !defined(__APPLE__) && !defined(_WIN32) && !defined(__MINGW32__) && \
     29     !defined(__CYGWIN__) && !defined(_AIX)
     30 #  define ZSTD_HAVE_WEAK_SYMBOLS 1
     31 #else
     32 #  define ZSTD_HAVE_WEAK_SYMBOLS 0
     33 #endif
     34 #if ZSTD_HAVE_WEAK_SYMBOLS
     35 #  define ZSTD_WEAK_ATTR __attribute__((__weak__))
     36 #else
     37 #  define ZSTD_WEAK_ATTR
     38 #endif
     39 
     40 /* Only enable tracing when weak symbols are available. */
     41 #ifndef ZSTD_TRACE
     42 #  define ZSTD_TRACE ZSTD_HAVE_WEAK_SYMBOLS
     43 #endif
     44 
     45 #if ZSTD_TRACE
     46 
     47 struct ZSTD_CCtx_s;
     48 struct ZSTD_DCtx_s;
     49 struct ZSTD_CCtx_params_s;
     50 
     51 typedef struct {
     52     /**
     53      * ZSTD_VERSION_NUMBER
     54      *
     55      * This is guaranteed to be the first member of ZSTD_trace.
     56      * Otherwise, this struct is not stable between versions. If
     57      * the version number does not match your expectation, you
     58      * should not interpret the rest of the struct.
     59      */
     60     unsigned version;
     61     /**
     62      * Non-zero if streaming (de)compression is used.
     63      */
     64     int streaming;
     65     /**
     66      * The dictionary ID.
     67      */
     68     unsigned dictionaryID;
     69     /**
     70      * Is the dictionary cold?
     71      * Only set on decompression.
     72      */
     73     int dictionaryIsCold;
     74     /**
     75      * The dictionary size or zero if no dictionary.
     76      */
     77     size_t dictionarySize;
     78     /**
     79      * The uncompressed size of the data.
     80      */
     81     size_t uncompressedSize;
     82     /**
     83      * The compressed size of the data.
     84      */
     85     size_t compressedSize;
     86     /**
     87      * The fully resolved CCtx parameters (NULL on decompression).
     88      */
     89     struct ZSTD_CCtx_params_s const* params;
     90     /**
     91      * The ZSTD_CCtx pointer (NULL on decompression).
     92      */
     93     struct ZSTD_CCtx_s const* cctx;
     94     /**
     95      * The ZSTD_DCtx pointer (NULL on compression).
     96      */
     97     struct ZSTD_DCtx_s const* dctx;
     98 } ZSTD_Trace;
     99 
    100 /**
    101  * A tracing context. It must be 0 when tracing is disabled.
    102  * Otherwise, any non-zero value returned by a tracing begin()
    103  * function is presented to any subsequent calls to end().
    104  *
    105  * Any non-zero value is treated as tracing is enabled and not
    106  * interpreted by the library.
    107  *
    108  * Two possible uses are:
    109  * * A timestamp for when the begin() function was called.
    110  * * A unique key identifying the (de)compression, like the
    111  *   address of the [dc]ctx pointer if you need to track
    112  *   more information than just a timestamp.
    113  */
    114 typedef unsigned long long ZSTD_TraceCtx;
    115 
    116 /**
    117  * Trace the beginning of a compression call.
    118  * @param cctx The dctx pointer for the compression.
    119  *             It can be used as a key to map begin() to end().
    120  * @returns Non-zero if tracing is enabled. The return value is
    121  *          passed to ZSTD_trace_compress_end().
    122  */
    123 ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_compress_begin(
    124     struct ZSTD_CCtx_s const* cctx);
    125 
    126 /**
    127  * Trace the end of a compression call.
    128  * @param ctx The return value of ZSTD_trace_compress_begin().
    129  * @param trace The zstd tracing info.
    130  */
    131 ZSTD_WEAK_ATTR void ZSTD_trace_compress_end(
    132     ZSTD_TraceCtx ctx,
    133     ZSTD_Trace const* trace);
    134 
    135 /**
    136  * Trace the beginning of a decompression call.
    137  * @param dctx The dctx pointer for the decompression.
    138  *             It can be used as a key to map begin() to end().
    139  * @returns Non-zero if tracing is enabled. The return value is
    140  *          passed to ZSTD_trace_compress_end().
    141  */
    142 ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_decompress_begin(
    143     struct ZSTD_DCtx_s const* dctx);
    144 
    145 /**
    146  * Trace the end of a decompression call.
    147  * @param ctx The return value of ZSTD_trace_decompress_begin().
    148  * @param trace The zstd tracing info.
    149  */
    150 ZSTD_WEAK_ATTR void ZSTD_trace_decompress_end(
    151     ZSTD_TraceCtx ctx,
    152     ZSTD_Trace const* trace);
    153 
    154 #endif /* ZSTD_TRACE */
    155 
    156 #endif /* ZSTD_TRACE_H */
    157