Skip to content

Restructure the project - #234

Merged
hovsep merged 1 commit into
mainfrom
revamp_project_layout
Jul 23, 2026
Merged

Restructure the project#234
hovsep merged 1 commit into
mainfrom
revamp_project_layout

Conversation

@hovsep

@hovsep hovsep commented Jul 23, 2026

Copy link
Copy Markdown
Owner

This pull request introduces several improvements and refactorings to the codebase, focusing on internal API organization, documentation, and test helper centralization. The most significant changes are the migration of the hook package to internal/hook (making it non-public), the addition of package-level documentation, and the consolidation of test helpers into a shared internal package. These changes clarify the public API surface, improve maintainability, and simplify test code.

Internal API organization and encapsulation:

  • Migrated the hook package to internal/hook, making it internal and not part of the public API; updated all references and documentation to reflect this change. (.agent/docs/design.md [1] .agent/docs/hooks.md [2] component/activation.go [3] component/hooks.go [4] hooks.go [5] docs/wiki/999.-Internals.md [6]
  • Renamed Plugins type to plugins (unexported) in component/plugin.go and component/component.go to clarify its internal usage. (component/plugin.go [1] component/component.go [2]

Documentation improvements:

  • Added package-level doc comments for component, cycle, and fmesh, providing clear overviews and usage guidance. (component/doc.go [1] cycle/doc.go [2] doc.go [3]
  • Clarified documentation for hooks and their internal status. (.agent/docs/hooks.md [1] .agent/docs/design.md [2] docs/wiki/999.-Internals.md [3]

Test helper centralization:

  • Moved common test helpers (e.g., mustComponent, mustInputPort) to internal/testutil for use across integration and external test packages; updated tests to use these shared helpers and removed local duplicates. (integration_tests/chainability/chainability_test.go [1] [2] [3] [4] [5] [6]; integration_tests/component_hooks/basic_test.go [7] [8] [9] [10] [11]
  • Updated .agent/docs/testing.md to document the shared test helper pattern and its location.

Testing and examples:

  • Added a new example_test.go file with a quick-start example demonstrating basic mesh setup and execution, mirroring the README.

Minor refactoring and consistency:

  • Changed MarkStarted/MarkStopped method calls to their unexported forms (markStarted/markStopped) for consistency with internal API conventions. (fmesh.go [1] [2] fmesh_test.go [3]
  • Removed unused local test helpers from fmesh_test.go and clarified comments about import cycles. [1] [2]

These changes collectively improve the clarity, maintainability, and testability of the codebase.

@hovsep
hovsep enabled auto-merge (rebase) July 23, 2026 14:10
@hovsep
hovsep force-pushed the revamp_project_layout branch from 6579217 to 5bd6402 Compare July 23, 2026 14:11
@hovsep
hovsep disabled auto-merge July 23, 2026 14:11
@hovsep
hovsep merged commit b721784 into main Jul 23, 2026
2 checks passed
@hovsep
hovsep deleted the revamp_project_layout branch July 23, 2026 14:11
@github-actions

Copy link
Copy Markdown

Benchmark report (advisory)

Statistically significant changes: 13 regression(s), 15 improvement(s) (PR head vs. base branch).

Benchmark Metric Base PR Δ
MeshRunWide/10-4 sec/op 79.25µ ± 4% 80.48µ ± 5% +1.55%
MeshRunWide/1000-4 sec/op 4.015m ± 1% 4.092m ± 2% +1.92%
MeshRunWide/10000-4 sec/op 44.16m ± 1% 44.91m ± 2% +1.68%
MeshFanIn/100-4 sec/op 555.0µ ± 0% 549.2µ ± 1% -1.05%
MeshFanIn/1000-4 sec/op 9.092m ± 1% 8.894m ± 2% -2.18%
MeshConstructionScale/1000-4 sec/op 3.937m ± 1% 3.891m ± 1% -1.15%
MeshRunFanOut-4 sec/op 80.60µ ± 0% 81.47µ ± 1% +1.08%
MeshThroughputDummy/huge-4 sec/op 918.1m ± 1% 944.5m ± 1% +2.87%
MeshThroughputBypass/small-4 sec/op 31.84m ± 1% 32.14m ± 1% +0.96%
MeshThroughputBypass/mid-4 sec/op 250.0m ± 0% 253.0m ± 2% +1.19%
MeshThroughputBypass/huge-4 sec/op 2.705 ± 3% 2.785 ± 3% +2.94%
MeshThroughputDummy/huge-4 activations/s 1.095M ± 1% 1.064M ± 2% -2.79%
MeshThroughputBypass/small-4 activations/s 315.7k ± 1% 312.7k ± 1% -0.95%
MeshThroughputBypass/mid-4 activations/s 401.9k ± 1% 397.2k ± 2% -1.18%
MeshThroughputBypass/huge-4 activations/s 371.5k ± 3% 360.9k ± 2% -2.86%
MeshThroughputDummy/huge-4 cycles/s 218.9 ± 1% 212.8 ± 2% -2.81%
MeshThroughputBypass/small-4 cycles/s 6.314k ± 1% 6.253k ± 1% -0.95%
MeshThroughputBypass/mid-4 cycles/s 803.9 ± 1% 794.4 ± 2% -1.18%
MeshThroughputBypass/huge-4 cycles/s 74.31 ± 3% 72.18 ± 2% -2.87%
ComponentHooks_Overhead/WithoutHooks-4 B/op 124.4Ki ± 5% 130.0Ki ± 4% +4.51%
ComponentHooks_Overhead/WithHooks-4 B/op 116.4Ki ± 2% 121.0Ki ± 7% +3.89%
GroupCoWOps-4 sec/op 97.27µ ± 0% 98.07µ ± 1% +0.82%
GroupBuild/10-4 sec/op 4.027µ ± 0% 4.070µ ± 0% +1.08%
GroupBuild/100-4 sec/op 54.79µ ± 1% 55.62µ ± 1% +1.51%
GroupPayloadSize/8-4 sec/op 1.671µ ± 1% 1.628µ ± 1% -2.60%
GroupPayloadSize/1024-4 sec/op 1.667µ ± 1% 1.625µ ± 1% -2.55%
GroupPayloadSize/65536-4 sec/op 1.679µ ± 1% 1.629µ ± 1% -3.01%
GroupPayloadSize/1048576-4 sec/op 1.781µ ± 1% 1.725µ ± 1% -3.17%

Higher is worse on every metric. allocs/op is the most reliable signal on shared CI runners; treat sec/op as guidance.

Full benchstat table
goos: linux
goarch: amd64
pkg: github.com/hovsep/fmesh
cpu: AMD EPYC 7763 64-Core Processor                
                              │  base.txt   │              pr.txt               │
                              │   sec/op    │   sec/op     vs base              │
MeshRunWide/10-4                79.25µ ± 4%   80.48µ ± 5%  +1.55% (p=0.007 n=8)
MeshRunWide/100-4               381.3µ ± 1%   380.4µ ± 1%       ~ (p=0.234 n=8)
MeshRunWide/1000-4              4.015m ± 1%   4.092m ± 2%  +1.92% (p=0.010 n=8)
MeshRunWide/10000-4             44.16m ± 1%   44.91m ± 2%  +1.68% (p=0.028 n=8)
MeshFanIn/10-4                  104.9µ ± 1%   105.5µ ± 1%       ~ (p=0.505 n=8)
MeshFanIn/100-4                 555.0µ ± 0%   549.2µ ± 1%  -1.05% (p=0.005 n=8)
MeshFanIn/1000-4                9.092m ± 1%   8.894m ± 2%  -2.18% (p=0.000 n=8)
MeshFanIn/10000-4               578.6m ± 1%   579.7m ± 2%       ~ (p=0.959 n=8)
MeshConstructionScale/10-4      36.81µ ± 0%   36.73µ ± 1%       ~ (p=1.000 n=8)
MeshConstructionScale/100-4     361.2µ ± 0%   360.5µ ± 1%       ~ (p=0.645 n=8)
MeshConstructionScale/1000-4    3.937m ± 1%   3.891m ± 1%  -1.15% (p=0.005 n=8)
MeshConstructionScale/10000-4   43.41m ± 2%   43.14m ± 1%       ~ (p=0.574 n=8)
MeshRunPipeline-4               139.9µ ± 0%   140.6µ ± 1%       ~ (p=0.328 n=8)
MeshRunFanOut-4                 80.60µ ± 0%   81.47µ ± 1%  +1.08% (p=0.000 n=8)
MeshConstruction-4              36.83µ ± 1%   36.75µ ± 0%       ~ (p=0.382 n=8)
MeshThroughputDummy/small-4     12.06m ± 0%   12.05m ± 1%       ~ (p=0.574 n=8)
MeshThroughputDummy/mid-4       93.74m ± 1%   93.27m ± 1%       ~ (p=0.130 n=8)
MeshThroughputDummy/huge-4      918.1m ± 1%   944.5m ± 1%  +2.87% (p=0.000 n=8)
MeshThroughputBypass/small-4    31.84m ± 1%   32.14m ± 1%  +0.96% (p=0.038 n=8)
MeshThroughputBypass/mid-4      250.0m ± 0%   253.0m ± 2%  +1.19% (p=0.050 n=8)
MeshThroughputBypass/huge-4      2.705 ± 3%    2.785 ± 3%  +2.94% (p=0.007 n=8)
geomean                         4.413m        4.431m       +0.42%

                              │   base.txt    │                pr.txt                 │
                              │     B/op      │     B/op       vs base                │
MeshRunWide/10-4                 16.11Ki ± 0%    16.11Ki ± 0%       ~ (p=1.000 n=8)
MeshRunWide/100-4                152.5Ki ± 0%    152.5Ki ± 0%       ~ (p=0.148 n=8)
MeshRunWide/1000-4               1.504Mi ± 0%    1.504Mi ± 0%       ~ (p=0.798 n=8)
MeshRunWide/10000-4              15.43Mi ± 0%    15.45Mi ± 0%       ~ (p=0.279 n=8)
MeshFanIn/10-4                   23.41Ki ± 0%    23.41Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshFanIn/100-4                  289.5Ki ± 0%    289.5Ki ± 0%       ~ (p=0.862 n=8)
MeshFanIn/1000-4                 10.18Mi ± 0%    10.18Mi ± 0%       ~ (p=0.204 n=8)
MeshFanIn/10000-4                838.2Mi ± 0%    838.2Mi ± 0%       ~ (p=0.105 n=8)
MeshConstructionScale/10-4       29.07Ki ± 0%    29.07Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshConstructionScale/100-4      283.5Ki ± 0%    283.5Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshConstructionScale/1000-4     2.805Mi ± 0%    2.805Mi ± 0%       ~ (p=0.267 n=8)
MeshConstructionScale/10000-4    27.84Mi ± 0%    27.84Mi ± 0%       ~ (p=0.979 n=8)
MeshRunPipeline-4                35.57Ki ± 0%    35.57Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshRunFanOut-4                  18.11Ki ± 0%    18.11Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshConstruction-4               29.07Ki ± 0%    29.07Ki ± 0%       ~ (p=1.000 n=8) ¹
MeshThroughputDummy/small-4      2.779Mi ± 0%    2.779Mi ± 0%       ~ (p=0.234 n=8)
MeshThroughputDummy/mid-4        30.50Mi ± 0%    30.50Mi ± 0%       ~ (p=1.000 n=8)
MeshThroughputDummy/huge-4       294.0Mi ± 0%    294.1Mi ± 0%       ~ (p=0.505 n=8)
MeshThroughputBypass/small-4     9.967Mi ± 0%    9.967Mi ± 0%       ~ (p=0.505 n=8)
MeshThroughputBypass/mid-4       102.4Mi ± 0%    102.4Mi ± 0%       ~ (p=0.328 n=8)
MeshThroughputBypass/huge-4     1012.9Mi ± 0%   1013.2Mi ± 0%       ~ (p=0.279 n=8)
geomean                          1.913Mi         1.913Mi       +0.01%
¹ all samples are equal

                              │  base.txt   │               pr.txt                │
                              │  allocs/op  │  allocs/op   vs base                │
MeshRunWide/10-4                 530.0 ± 0%    530.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshRunWide/100-4               4.862k ± 0%   4.862k ± 0%       ~ (p=1.000 n=8) ¹
MeshRunWide/1000-4              48.99k ± 0%   48.99k ± 0%       ~ (p=0.462 n=8)
MeshRunWide/10000-4             490.1k ± 0%   490.3k ± 0%       ~ (p=0.342 n=8)
MeshFanIn/10-4                   744.0 ± 0%    744.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshFanIn/100-4                 6.699k ± 0%   6.699k ± 0%       ~ (p=1.000 n=8) ¹
MeshFanIn/1000-4                67.03k ± 0%   67.03k ± 0%       ~ (p=0.220 n=8)
MeshFanIn/10000-4               670.1k ± 0%   670.1k ± 0%       ~ (p=0.104 n=8)
MeshConstructionScale/10-4       809.0 ± 0%    809.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshConstructionScale/100-4     7.835k ± 0%   7.835k ± 0%       ~ (p=1.000 n=8) ¹
MeshConstructionScale/1000-4    78.95k ± 0%   78.95k ± 0%       ~ (p=1.000 n=8) ¹
MeshConstructionScale/10000-4   790.0k ± 0%   790.0k ± 0%       ~ (p=1.000 n=8) ¹
MeshRunPipeline-4                980.0 ± 0%    980.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshRunFanOut-4                  572.0 ± 0%    572.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshConstruction-4               809.0 ± 0%    809.0 ± 0%       ~ (p=1.000 n=8) ¹
MeshThroughputDummy/small-4     67.15k ± 0%   67.15k ± 0%       ~ (p=0.097 n=8)
MeshThroughputDummy/mid-4       621.6k ± 0%   621.6k ± 0%       ~ (p=0.939 n=8)
MeshThroughputDummy/huge-4      6.154M ± 0%   6.154M ± 0%       ~ (p=0.505 n=8)
MeshThroughputBypass/small-4    337.8k ± 0%   337.8k ± 0%       ~ (p=0.505 n=8)
MeshThroughputBypass/mid-4      3.328M ± 0%   3.328M ± 0%       ~ (p=0.314 n=8)
MeshThroughputBypass/huge-4     33.22M ± 0%   33.22M ± 0%       ~ (p=0.279 n=8)
geomean                         43.35k        43.35k       +0.00%
¹ all samples are equal

                             │   base.txt    │               pr.txt                │
                             │ activations/s │ activations/s  vs base              │
MeshThroughputDummy/small-4      833.2k ± 1%     834.2k ± 0%       ~ (p=0.574 n=8)
MeshThroughputDummy/mid-4        1.072M ± 1%     1.078M ± 1%       ~ (p=0.130 n=8)
MeshThroughputDummy/huge-4       1.095M ± 1%     1.064M ± 2%  -2.79% (p=0.000 n=8)
MeshThroughputBypass/small-4     315.7k ± 1%     312.7k ± 1%  -0.95% (p=0.038 n=8)
MeshThroughputBypass/mid-4       401.9k ± 1%     397.2k ± 2%  -1.18% (p=0.050 n=8)
MeshThroughputBypass/huge-4      371.5k ± 3%     360.9k ± 2%  -2.86% (p=0.007 n=8)
geomean                          598.8k          591.6k       -1.20%

                             │  base.txt   │              pr.txt               │
                             │  cycles/s   │  cycles/s    vs base              │
MeshThroughputDummy/small-4    16.66k ± 1%   16.68k ± 0%       ~ (p=0.554 n=8)
MeshThroughputDummy/mid-4      2.144k ± 1%   2.155k ± 1%       ~ (p=0.130 n=8)
MeshThroughputDummy/huge-4      218.9 ± 1%    212.8 ± 2%  -2.81% (p=0.000 n=8)
MeshThroughputBypass/small-4   6.314k ± 1%   6.253k ± 1%  -0.95% (p=0.038 n=8)
MeshThroughputBypass/mid-4      803.9 ± 1%    794.4 ± 2%  -1.18% (p=0.047 n=8)
MeshThroughputBypass/huge-4     74.31 ± 3%    72.18 ± 2%  -2.87% (p=0.007 n=8)
geomean                        1.198k        1.183k       -1.20%

pkg: github.com/hovsep/fmesh/integration_tests/component_hooks
                                       │  base.txt   │              pr.txt               │
                                       │   sec/op    │   sec/op     vs base              │
ComponentHooks_Overhead/WithoutHooks-4   122.7µ ± 1%   122.7µ ± 2%       ~ (p=0.645 n=8)
ComponentHooks_Overhead/WithHooks-4      123.5µ ± 2%   123.3µ ± 1%       ~ (p=0.574 n=8)
geomean                                  123.1µ        123.0µ       -0.09%

                                       │   base.txt   │               pr.txt               │
                                       │     B/op     │     B/op      vs base              │
ComponentHooks_Overhead/WithoutHooks-4   124.4Ki ± 5%   130.0Ki ± 4%  +4.51% (p=0.038 n=8)
ComponentHooks_Overhead/WithHooks-4      116.4Ki ± 2%   121.0Ki ± 7%  +3.89% (p=0.002 n=8)
geomean                                  120.4Ki        125.4Ki       +4.20%

                                       │  base.txt  │               pr.txt               │
                                       │ allocs/op  │ allocs/op   vs base                │
ComponentHooks_Overhead/WithoutHooks-4   18.00 ± 0%   18.00 ± 0%       ~ (p=1.000 n=8) ¹
ComponentHooks_Overhead/WithHooks-4      18.00 ± 0%   18.00 ± 0%       ~ (p=1.000 n=8) ¹
geomean                                  18.00        18.00       +0.00%
¹ all samples are equal

pkg: github.com/hovsep/fmesh/signal
                           │  base.txt   │              pr.txt               │
                           │   sec/op    │   sec/op     vs base              │
GroupCoWOps-4                97.27µ ± 0%   98.07µ ± 1%  +0.82% (p=0.038 n=8)
GroupScalarAggregation-4     2.849µ ± 2%   2.847µ ± 1%       ~ (p=0.664 n=8)
GroupBuild/10-4              4.027µ ± 0%   4.070µ ± 0%  +1.08% (p=0.000 n=8)
GroupBuild/100-4             54.79µ ± 1%   55.62µ ± 1%  +1.51% (p=0.010 n=8)
GroupBuild/1000-4            2.223m ± 4%   2.264m ± 6%       ~ (p=0.161 n=8)
GroupBuild/10000-4           717.2m ± 3%   704.7m ± 2%       ~ (p=0.130 n=8)
GroupPayloadSize/8-4         1.671µ ± 1%   1.628µ ± 1%  -2.60% (p=0.000 n=8)
GroupPayloadSize/1024-4      1.667µ ± 1%   1.625µ ± 1%  -2.55% (p=0.000 n=8)
GroupPayloadSize/65536-4     1.679µ ± 1%   1.629µ ± 1%  -3.01% (p=0.000 n=8)
GroupPayloadSize/1048576-4   1.781µ ± 1%   1.725µ ± 1%  -3.17% (p=0.000 n=8)
geomean                      30.97µ        30.72µ       -0.81%

                           │    base.txt    │                pr.txt                │
                           │      B/op      │     B/op      vs base                │
GroupCoWOps-4                137.1Ki ± 0%     137.1Ki ± 0%       ~ (p=1.000 n=8)
GroupScalarAggregation-4       0.000 ± 0%       0.000 ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/10-4              4.266Ki ± 0%     4.266Ki ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/100-4             116.0Ki ± 0%     116.0Ki ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/1000-4            8.493Mi ± 0%     8.493Mi ± 0%       ~ (p=0.193 n=8)
GroupBuild/10000-4           820.7Mi ± 0%     820.7Mi ± 0%       ~ (p=0.382 n=8)
GroupPayloadSize/8-4         2.422Ki ± 0%     2.422Ki ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/1024-4      2.422Ki ± 0%     2.422Ki ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/65536-4     2.422Ki ± 0%     2.422Ki ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/1048576-4   2.422Ki ± 0%     2.422Ki ± 0%       ~ (p=1.000 n=8) ¹
geomean                                   ²                 -0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

                           │   base.txt    │               pr.txt                │
                           │   allocs/op   │  allocs/op   vs base                │
GroupCoWOps-4                1.635k ± 0%     1.635k ± 0%       ~ (p=1.000 n=8) ¹
GroupScalarAggregation-4      0.000 ± 0%      0.000 ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/10-4               131.0 ± 0%      131.0 ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/100-4             1.301k ± 0%     1.301k ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/1000-4            13.74k ± 0%     13.74k ± 0%       ~ (p=1.000 n=8) ¹
GroupBuild/10000-4           139.8k ± 0%     139.8k ± 0%       ~ (p=0.593 n=8)
GroupPayloadSize/8-4          31.00 ± 0%      31.00 ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/1024-4       31.00 ± 0%      31.00 ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/65536-4      31.00 ± 0%      31.00 ± 0%       ~ (p=1.000 n=8) ¹
GroupPayloadSize/1048576-4    31.00 ± 0%      31.00 ± 0%       ~ (p=1.000 n=8) ¹
geomean                                  ²                -0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant