profile

Documentation

Overview

Package profile provides a simple way to generate pprof compatible gnark circuit profile.

Since the gnark frontend compiler is not thread safe and operates in a single go-routine, this package is also NOT thread safe and is meant to be called in the same go-routine.

Example

//go:build !windows

package main

import (
	"fmt"

	"github.com/consensys/gnark-crypto/ecc"
	"github.com/consensys/gnark/frontend"
	"github.com/consensys/gnark/frontend/cs/r1cs"
	"github.com/consensys/gnark/profile"
)

type Circuit struct {
	A frontend.Variable
}

type obj struct {
}

func (circuit *Circuit) Define(api frontend.API) error {
	var o obj
	o.Define(api, circuit.A)
	// api.AssertIsEqual(api.Mul(circuit.A, circuit.A), circuit.A)
	return nil
}

func (o *obj) Define(api frontend.API, A frontend.Variable) error {
	api.AssertIsEqual(api.Mul(A, A), A)
	return nil
}

func main() {
	// default options generate gnark.pprof in current dir
	// use pprof as usual (go tool pprof -http=:8080 gnark.pprof) to read the profile file
	// overlapping profiles are allowed (define profiles inside Define or subfunction to profile
	// part of the circuit only)
	p := profile.Start()
	_, _ = frontend.Compile(ecc.BN254.ScalarField(), r1cs.NewBuilder, &Circuit{})
	p.Stop()

	// expected output fmt.Println(p.Top())
	const _ = `Showing nodes accounting for 2, 100% of 2 total
----------------------------------------------------------+-------------
      flat  flat%   sum%        cum   cum%   calls calls% + context              
----------------------------------------------------------+-------------
                                                 1   100% |   profile_test.(*Circuit).Define profile/profile_test.go:21
         1 50.00% 50.00%          1 50.00%                | r1cs.(*builder).AssertIsEqual frontend/cs/r1cs/api_assertions.go:37
----------------------------------------------------------+-------------
                                                 1   100% |   profile_test.(*Circuit).Define profile/profile_test.go:21
         1 50.00%   100%          1 50.00%                | r1cs.(*builder).Mul frontend/cs/r1cs/api.go:221
----------------------------------------------------------+-------------
         0     0%   100%          2   100%                | profile_test.(*Circuit).Define profile/profile_test.go:21
                                                 1 50.00% |   r1cs.(*builder).AssertIsEqual frontend/cs/r1cs/api_assertions.go:37
                                                 1 50.00% |   r1cs.(*builder).Mul frontend/cs/r1cs/api.go:221
----------------------------------------------------------+-------------`

	fmt.Println(p.NbConstraints())
}

Output:

2

Index

• func RecordConstraint()
• type Option
  • func WithNoOutput() Option
  • func WithPath(path string) Option
• type Profile
  • func Start(options ...Option) *Profile
  • func (p *Profile) NbConstraints() int
  • func (p *Profile) Stop()
  • func (p *Profile) Top() string

Examples

• Package

Functions

func RecordConstraint

func RecordConstraint()

RecordConstraint add a sample (with count == 1) to all the active profiling sessions.

Types

type Option

type Option func(*Profile)

Option defines configuration Options for Profile.

func WithNoOutput

func WithNoOutput() Option

WithNoOutput indicates that the profile is not going to be written to disk.

This is equivalent to WithPath("")

func WithPath

func WithPath(path string) Option

WithPath controls the profile destination file. If blank, profile is not written.

Defaults to ./gnark.pprof.

type Profile

type Profile struct {
	// contains filtered or unexported fields
}

Profile represents an active constraint system profiling session.

func Start

func Start(options ...Option) *Profile

Start creates a new active profiling session. When Stop() is called, this session is removed from active profiling sessions and may be serialized to disk as a pprof compatible file (see ProfilePath option).

All calls to profile.Start() and Stop() are meant to be executed in the same go routine (frontend.Compile).

It is allowed to create multiple overlapping profiling sessions in one circuit.

func (*Profile) NbConstraints

func (p *Profile) NbConstraints() int

NbConstraints return number of collected samples (constraints) by the profile session

func (*Profile) Stop

func (p *Profile) Stop()

Stop removes the profile from active session and may write the pprof file to disk. See ProfilePath option.

func (*Profile) Top

func (p *Profile) Top() string

Top return a similar output than pprof top command