10.5 Manuale di riferimento

Il punto di entrata iniziale del profiler � la funzione globale profile.run(). Essa viene tipicamente utilizzata per creare tutte le informazione di profilo. I risultati vengono formattati e stampati usando i metodi della classe pstats.Stats. Ci� che segue � una descrizione di tutte queste funzioni e punti d'ingresso standard. Per una visione pi� approfondita di alcune porzioni di codice, prendete in considerazione la lettura della sezione successiva sulle Estensioni al Profiler, che spiega come derivare profiler ``migliori'' dalla classe qui presentata, oppure leggendo il codice sorgente di questi moduli.

run( command[, filename])

Questa funzione richiede un singolo argomento che possa venire passato all'istruzione exec ed un nome di file facoltativo. In tutti i casi questa procedura tenta di eseguire tramite exec il suo primo argomento, costruendo un profilo dalla sua esecuzione. Se non � presente un nome di file questa funzione stampa automaticamente a video un semplice profilo, ordinando ogni riga secondo la stringa standard (file/riga/nome-funzione). Ecco l'output tipico di questa chiamata:

      main()
      2706 function calls (2004 primitive calls) in 4.504 CPU seconds

Ordered by: standard name

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
  43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
 ...

La prima riga indica che questo profilo � stato generato dalla chiamata:
profile.run('main()') e quindi la stringa passata ad exec � stata 'main()'. La seconda riga indica che sono state monitorate 2706 chiamate di funzione. Di queste, 2004 erano chiamate primitive. Per primitiva si intende una chiamata che non � stata indotta tramite ricorsione. La riga successiva: Ordered by: standard name, indica che l'ordinamento delle righe � avvenuto in base alla stringa presente nella colonna pi� a destra. Le intestazioni delle colonne includono:

ncalls: il numero di chiamate,
tottime: il tempo totale speso in questa funzione (escludendo il tempo trascorso per chiamare altre sotto funzioni),
percall: il rapporto tra tottime e ncalls
cumtime: il tempo totale speso dalla funzione corrente e da tutte le sue sotto funzioni(dall'invocazione all'uscita). Il risultato comprende anche le funzioni ricorsive.
percall: il rapporto tra cumtime ed il numero di chiamate primitive
filename:lineno(function): fornisce informazioni su ogni funzione

Quando ci sono due numeri nella prima colonna (per esempio, "43/3"), allora il secondo � il numero di chiamate primitive, mentre il primo � il numero di chiamate reali. Notate che quando una funzione non � ricorsiva, questi due numeri sono identici, e quindi ne viene stampato solo uno.

runctx( command, globals, locals[, filename])

Questa funzione � simile a profile.run(), con argomenti aggiuntivi per supplire ai dizionari locali e globali per la stringa command.

L'analisi dei dati prodotti dal profiler si esegue usando la classe definita nel modulo pstats:

class Stats( filename[, ...])

Il costruttore di questa classe crea un'istanza di un ``oggetto delle statistiche'' a partire da uno o pi� nomi di file filename. Gli oggetti di tipo Stats posseggono dei metodi per manipolare e stampare statistiche utili.

Il file passato al costruttore deve essere stato creato dalla corrispondente versione di profile. In particolare, non viene garantita la compatibilit� del formato del file con future versioni del profiler, e non c'� alcuna compatibilit� con i file generati da altri profiler (come il vecchio profiler di sistema).

Se vengono passati al costruttore vari file, tutte le statistiche di una funzione vengono riunite in una sola, cosicch� si possa avere in un unico rapporto la visione generale di vari processi. Se dopo la creazione dell'oggetto Stats si ha la necessit� di combinare i suoi dati con altri file aggiuntivi, si pu� sempre utilizzare il metodo add().

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.