From 8063a5cc068e2e275dafb3451c2f806228bc311d Mon Sep 17 00:00:00 2001 From: Victor Zhang Date: Fri, 13 Mar 2026 11:21:43 -0700 Subject: [PATCH] Stage 1: Rename WAYPOINT to CWAYPOINT for compress introspection (#511) Summary: Pull Request resolved: https://github.com/facebook/openzl/pull/511 Renames the existing compress-only WAYPOINT macro to CWAYPOINT (and IF_WAYPOINT_ENABLED to IF_CWAYPOINT_ENABLED) across the codebase. Splits hasIntrospectionHooks into hasCompressionHooks and hasDecompressionHooks bools in ZL_OperationContext, and renames introspectionHooks to compressIntrospectionHooks. This prepares the codebase for adding decompression-side introspection hooks without naming ambiguity. Reviewed By: terrelln Differential Revision: D96049307 --- src/openzl/common/introspection.h | 46 ++++++++++--------- src/openzl/common/operation_context.c | 3 +- src/openzl/common/operation_context.h | 9 ++-- src/openzl/compress/cctx.c | 25 +++++----- src/openzl/compress/compress2.c | 4 +- src/openzl/compress/dyngraph_interface.c | 2 +- src/openzl/compress/enc_interface.c | 16 +++---- src/openzl/compress/segmenter.c | 4 +- .../CompressIntrospectionTest.cpp | 2 +- 9 files changed, 59 insertions(+), 52 deletions(-) diff --git a/src/openzl/common/introspection.h b/src/openzl/common/introspection.h index dfd500c34..b957c8657 100644 --- a/src/openzl/common/introspection.h +++ b/src/openzl/common/introspection.h @@ -13,42 +13,44 @@ extern "C" { #if ZL_ALLOW_INTROSPECTION /** - * Define an execution waypoint for introspection. When inserted into an - * existing code block, this macro will grab the relevant OperationContext from - * the @p ctx object and call the corresponding @p hook function at the point of - * insertion. + * Define an execution waypoint for compression introspection. When inserted + * into an existing code block, this macro will grab the relevant + * OperationContext from the @p ctx object and call the corresponding @p hook + * function at the point of insertion. * * If @p hook is not provided (function pointer points to NULL), the operation * is aborted. This is to save on the expensive computation to fill __VA_ARGS__. - * If introspection is disabled, the whole WAYPOINT macro is no-oped. + * If introspection is disabled, the whole CWAYPOINT macro is no-oped. * * @note @p ctx must be a valid context object from which the OperationContext * can be extracted. */ -# define WAYPOINT(hook, ctx, ...) \ - do { \ - ZL_OperationContext* _oc = ZL_GET_OPERATION_CONTEXT(ctx); \ - ZL_ASSERT_NN(_oc); \ - if (!_oc->hasIntrospectionHooks) { \ - break; \ - } \ - if (_oc->introspectionHooks.hook != NULL) { \ - /* allow passing a C++ class */ \ - _oc->introspectionHooks.hook( \ - _oc->introspectionHooks.opaque, ctx, __VA_ARGS__); \ - } \ +# define CWAYPOINT(hook, ctx, ...) \ + do { \ + ZL_OperationContext* _oc = ZL_GET_OPERATION_CONTEXT(ctx); \ + ZL_ASSERT_NN(_oc); \ + if (!_oc->hasCompressionHooks) { \ + break; \ + } \ + if (_oc->compressIntrospectionHooks.hook != NULL) { \ + /* allow passing a C++ class */ \ + _oc->compressIntrospectionHooks.hook( \ + _oc->compressIntrospectionHooks.opaque, \ + ctx, \ + __VA_ARGS__); \ + } \ } while (0) -# define IF_WAYPOINT_ENABLED(hook, ctx) \ +# define IF_CWAYPOINT_ENABLED(hook, ctx) \ ZL_OperationContext* _wpe_oc##hook = ZL_GET_OPERATION_CONTEXT(ctx); \ ZL_ASSERT_NN(_wpe_oc##hook); \ - if (_wpe_oc##hook->hasIntrospectionHooks \ - && _wpe_oc##hook->introspectionHooks.hook != NULL) + if (_wpe_oc##hook->hasCompressionHooks \ + && _wpe_oc##hook->compressIntrospectionHooks.hook != NULL) #else -# define WAYPOINT(hook, ctx, ...) -# define IF_WAYPOINT_ENABLED(hook, ctx) if (false) +# define CWAYPOINT(hook, ctx, ...) +# define IF_CWAYPOINT_ENABLED(hook, ctx) if (false) #endif diff --git a/src/openzl/common/operation_context.c b/src/openzl/common/operation_context.c index 5c9154fd3..8f0f35393 100644 --- a/src/openzl/common/operation_context.c +++ b/src/openzl/common/operation_context.c @@ -15,7 +15,8 @@ void ZL_OC_init(ZL_OperationContext* opCtx) memset(opCtx, 0, sizeof(*opCtx)); VECTOR_INIT(opCtx->errorInfos, 1024); VECTOR_INIT(opCtx->warnings, 1024); - opCtx->hasIntrospectionHooks = false; + opCtx->hasCompressionHooks = false; + opCtx->hasDecompressionHooks = false; } void ZL_OC_destroy(ZL_OperationContext* opCtx) diff --git a/src/openzl/common/operation_context.h b/src/openzl/common/operation_context.h index 9a21fbd21..6be0ae6c2 100644 --- a/src/openzl/common/operation_context.h +++ b/src/openzl/common/operation_context.h @@ -52,10 +52,11 @@ struct ZL_OperationContext_s { // Introspection hooks for the current operation. Realistically only // relevant for CCtx and DCtx. These allow the user to execute custom code - // snippets at specified WAYPOINT()s within the operation. See - // common/introspection.h for more details. - ZL_CompressIntrospectionHooks introspectionHooks; - bool hasIntrospectionHooks; + // snippets at specified CWAYPOINT()s / DWAYPOINT()s within the operation. + // See common/introspection.h for more details. + ZL_CompressIntrospectionHooks compressIntrospectionHooks; + bool hasCompressionHooks; + bool hasDecompressionHooks; }; void ZL_OC_init(ZL_OperationContext* opCtx); diff --git a/src/openzl/compress/cctx.c b/src/openzl/compress/cctx.c index 455778725..f12e2f71a 100644 --- a/src/openzl/compress/cctx.c +++ b/src/openzl/compress/cctx.c @@ -242,8 +242,8 @@ ZL_Report ZL_CCtx_attachIntrospectionHooks( ZL_ERR_IF_NULL(hooks, allocation); ZL_OperationContext* oc = ZL_CCtx_getOperationContext(cctx); ZL_ASSERT_NN(oc); - oc->introspectionHooks = *hooks; - oc->hasIntrospectionHooks = true; + oc->compressIntrospectionHooks = *hooks; + oc->hasCompressionHooks = true; return ZL_returnSuccess(); } @@ -252,8 +252,10 @@ ZL_Report ZL_CCtx_detachAllIntrospectionHooks(ZL_CCtx* cctx) ZL_ASSERT_NN(cctx); ZL_OperationContext* oc = ZL_CCtx_getOperationContext(cctx); ZL_ASSERT_NN(oc); - ZL_zeroes(&oc->introspectionHooks, sizeof(oc->introspectionHooks)); - oc->hasIntrospectionHooks = false; + ZL_zeroes( + &oc->compressIntrospectionHooks, + sizeof(oc->compressIntrospectionHooks)); + oc->hasCompressionHooks = false; return ZL_returnSuccess(); } @@ -640,7 +642,7 @@ static ZL_Report CCTX_convertInputs( input, inType, portTypeMask); - WAYPOINT( + CWAYPOINT( on_cctx_convertOneInput, cctx, input, @@ -788,7 +790,7 @@ static ZL_Report CCTX_runGraph_internal( (void)graphid; // required only for waypoints // All streams created after this index will be created by the dynamic // graph - WAYPOINT( + CWAYPOINT( on_migraphEncode_start, gctx, CCTX_getCGraph(cctx), @@ -797,10 +799,11 @@ static ZL_Report CCTX_runGraph_internal( nbInputs); ZL_Report const graphExecutionReport = GCTX_runMultiInputGraph(gctx, inputs, nbInputs); - IF_WAYPOINT_ENABLED(on_migraphEncode_end, gctx) + IF_CWAYPOINT_ENABLED(on_migraphEncode_end, gctx) { if (ZL_isError(graphExecutionReport)) { - WAYPOINT(on_migraphEncode_end, gctx, NULL, 0, graphExecutionReport); + CWAYPOINT( + on_migraphEncode_end, gctx, NULL, 0, graphExecutionReport); } else { size_t nbSuccs = VECTOR_SIZE(gctx->dstGraphDescs); DECLARE_VECTOR_TYPE(ZL_GraphID); @@ -814,7 +817,7 @@ static ZL_Report CCTX_runGraph_internal( allocation, "Unable to append to the waypoint succGids vector"); } - WAYPOINT( + CWAYPOINT( on_migraphEncode_end, gctx, VECTOR_DATA(succGids), @@ -983,9 +986,9 @@ static ZL_Report CCTX_runSegmenter( &cctx->rtgraph, cctx->sessionArena, cctx->chunkArena); - WAYPOINT(on_segmenterEncode_start, segmenterCtx, /* placeholder */ NULL); + CWAYPOINT(on_segmenterEncode_start, segmenterCtx, /* placeholder */ NULL); const ZL_Report r = SEGM_runSegmenter(segmenterCtx); - WAYPOINT(on_segmenterEncode_end, segmenterCtx, r); + CWAYPOINT(on_segmenterEncode_end, segmenterCtx, r); // Maybe clean up on-the-fly materialized params MPM_dematerializeOneshot(cctx->sessionArena, &segMatRes); diff --git a/src/openzl/compress/compress2.c b/src/openzl/compress/compress2.c index 1ab20ce2f..b14d8f8ec 100644 --- a/src/openzl/compress/compress2.c +++ b/src/openzl/compress/compress2.c @@ -340,7 +340,7 @@ ZL_Report ZL_CCtx_compressMultiTypedRef( size_t nbInputs) { ZL_RESULT_DECLARE_SCOPE_REPORT(cctx); - WAYPOINT( + CWAYPOINT( on_ZL_CCtx_compressMultiTypedRef_start, cctx, dst, @@ -354,7 +354,7 @@ ZL_Report ZL_CCtx_compressMultiTypedRef( ZL_ERR_IF_NOT(CCTX_isGraphSet(cctx), compressionParameter_invalid); const ZL_Report rep = CCTX_compressInputs_withGraphSet( cctx, dst, dstCapacity, ZL_codemodInputsAsDatas(inputs), nbInputs); - WAYPOINT(on_ZL_CCtx_compressMultiTypedRef_end, cctx, rep); + CWAYPOINT(on_ZL_CCtx_compressMultiTypedRef_end, cctx, rep); return rep; } diff --git a/src/openzl/compress/dyngraph_interface.c b/src/openzl/compress/dyngraph_interface.c index 0be3b2b45..8a3162714 100644 --- a/src/openzl/compress/dyngraph_interface.c +++ b/src/openzl/compress/dyngraph_interface.c @@ -126,7 +126,7 @@ bool ZL_Graph_isNodeSupported(const ZL_Graph* gctx, ZL_NodeID nodeid) void* ZL_Graph_getScratchSpace(ZL_Graph* gctx, size_t size) { - WAYPOINT(on_ZL_Graph_getScratchSpace, gctx, size); + CWAYPOINT(on_ZL_Graph_getScratchSpace, gctx, size); return ALLOC_Arena_malloc(gctx->graphArena, size); } diff --git a/src/openzl/compress/enc_interface.c b/src/openzl/compress/enc_interface.c index f7c23cf87..61c085d96 100644 --- a/src/openzl/compress/enc_interface.c +++ b/src/openzl/compress/enc_interface.c @@ -104,7 +104,7 @@ void ZL_Encoder_sendCodecHeader( size_t trhSize) { ZL_DLOG(SEQ, "ZL_Encoder_sendCodecHeader (%zu bytes)", trhSize); - WAYPOINT(on_ZL_Encoder_sendCodecHeader, eictx, trh, trhSize); + CWAYPOINT(on_ZL_Encoder_sendCodecHeader, eictx, trh, trhSize); ZL_ASSERT_NN(eictx); if (trhSize) ZL_ASSERT_NN(trh); @@ -183,7 +183,7 @@ ZL_Output* ZL_Encoder_createTypedStream( ZL_ASSERT_NN(eic); ZL_Data* ret = CCTX_getNewStream( eic->cctx, eic->rtnodeid, outStreamIndex, eltWidth, eltsCapacity); - WAYPOINT( + CWAYPOINT( on_ZL_Encoder_createTypedStream, eic, outStreamIndex, @@ -259,9 +259,9 @@ static ZL_Report ENC_runTransform_internal( // Run transform ZL_ASSERT_NN(trDesc->publicDesc.transform_f); - IF_WAYPOINT_ENABLED(on_codecEncode_start, eictx) + IF_CWAYPOINT_ENABLED(on_codecEncode_start, eictx) { - WAYPOINT( + CWAYPOINT( on_codecEncode_start, eictx, CCTX_getCGraph(eictx->cctx), @@ -272,13 +272,13 @@ static ZL_Report ENC_runTransform_internal( ZL_Report codecExecResult = (trDesc->publicDesc.transform_f( eictx, ZL_codemodDatasAsInputs(inStreams), nbInStreams)); if (ZL_isError(codecExecResult)) { - WAYPOINT(on_codecEncode_end, eictx, NULL, 0, codecExecResult); + CWAYPOINT(on_codecEncode_end, eictx, NULL, 0, codecExecResult); ZL_RET_R_IF_ERR_COERCE( codecExecResult, "transform %s failed", CT_getTrName(trDesc)); } const RTGraph* rtgm = CCTX_getRTGraph(eictx->cctx); const size_t nbOutStreams = RTGM_getNbOutStreams(rtgm, eictx->rtnodeid); - IF_WAYPOINT_ENABLED(on_codecEncode_end, eictx) + IF_CWAYPOINT_ENABLED(on_codecEncode_end, eictx) { DECLARE_VECTOR_CONST_POINTERS_TYPE(ZL_Data); VECTOR_CONST_POINTERS(ZL_Data) odata; @@ -293,7 +293,7 @@ static ZL_Report ENC_runTransform_internal( allocation, "Unable to append to the waypoint odata vector"); } - WAYPOINT( + CWAYPOINT( on_codecEncode_end, eictx, ZL_codemodConstDatasAsOutputs(VECTOR_DATA(odata)), @@ -365,7 +365,7 @@ ZL_Report ENC_runTransform( void* ZL_Encoder_getScratchSpace(ZL_Encoder* ei, size_t size) { - WAYPOINT(on_ZL_Encoder_getScratchSpace, ei, size); + CWAYPOINT(on_ZL_Encoder_getScratchSpace, ei, size); return ALLOC_Arena_malloc(ei->wkspArena, size); } diff --git a/src/openzl/compress/segmenter.c b/src/openzl/compress/segmenter.c index 9964ad91e..67604e647 100644 --- a/src/openzl/compress/segmenter.c +++ b/src/openzl/compress/segmenter.c @@ -266,7 +266,7 @@ ZL_Report ZL_Segmenter_processChunk( ZL_GraphID startingGraphID, const ZL_RuntimeGraphParameters* rGraphParams) { - WAYPOINT( + CWAYPOINT( on_ZL_Segmenter_processChunk_start, segCtx, numElts, @@ -333,7 +333,7 @@ ZL_Report ZL_Segmenter_processChunk( } CCTX_cleanChunk(cctx); - WAYPOINT(on_ZL_Segmenter_processChunk_end, segCtx, r); + CWAYPOINT(on_ZL_Segmenter_processChunk_end, segCtx, r); return r; } diff --git a/tests/integrationtest/CompressIntrospectionTest.cpp b/tests/integrationtest/CompressIntrospectionTest.cpp index 23db5b0d3..0d24dc8c7 100644 --- a/tests/integrationtest/CompressIntrospectionTest.cpp +++ b/tests/integrationtest/CompressIntrospectionTest.cpp @@ -97,7 +97,7 @@ TEST(CompressIntrospectionTest, IFnoHooksTHENnoop) // code snippet containing a waypoint static int func(ZL_CCtx* cctx) { - IF_WAYPOINT_ENABLED(on_codecEncode_start, cctx) + IF_CWAYPOINT_ENABLED(on_codecEncode_start, cctx) { return 1; }