L'objet Debugger

Lors d'un appel au constructeur, l'objet Debugger crée une nouvelle instance de Debugger.

new Debugger([global, …])
Crée un objet debugger, et appliquer la méthode addDebuggee a chacun des objets globaux passés en paramètre, afin de les ajouter comme les cibles de débogage initiales.

Propriétées d'accession du prototype de l'objet Debugger

Une instance Debugger hérite des propriétés suivantes de son prototype :

enabled

Un booléen indiquant si les handlers, breakpoints, et autres de l'instance Debugger  sont actives. C'est une propriété d'accession avec un getter et setter. La propriété est à true par défaut pour une nouvelle instance de Debugger.

Cette propriété donne un point de contrôle unique pour que le debugguger puisse se dépêtrer de la cible déboguée. Qu'importe les évènements ou hadlers ajoutés à l'interface.

allowUnobservedAsmJS

Un booléen inquant si le code asm.js s'exécutant dans les globales de la cible déboguée de l'instance Debugger est invisible à l'API du Debugger et aux points d'arrêts. Passer cette variable à false empêche asm.js prémptif et force le code asm.js à s'exécuter comem du code JavaScript normal.code to run as normal JavaScript. C'est une propriété d'accession avec un getter et setter. La propriété est à false par défaut pour une nouvelle instance de Debugger.

Passer cette variable à true est prévu principalement pour les utilisations des sous-systèmes de l'API Debugger API (par exemple Debugger.Source) autre que le débogage pas à pas d'un programme cible JavaScript.

allowWasmBinarySource
Un booléen indiquant si les sources WebAssembly seront disponibles sous forme binaire. La génération en texte WebAssembly sera désactivée.
collectCoverageInfo

Un booléen indiquant si la couverture (coverage) du code doit être activé dans chaque cible de débogue de l'instance. Modifier cette valeur recompilera tout le code JIT pour ajouter ou supprimer l'instrumentation de la couverture du code. Changer cette valeur lorsqu'une trame d'ne des cibles déboguées est active sur la pile générera une exception.

Passer cette valeur à true active l'instrumentation de la  couverture du code (code coverage instrumentation), qui peut alors être accédée via la fonction getOffsetsCoverage de Debugger.Script. Dans certains cas, la couverture du code peut exposer les informations avant la modification de la variable. Les rapports de couverture sont monotones, et donc il est possible de prendre une capture lorsque le Déboggeur est activé, puis d'afficher la différence.

Passer cette valeur à false empêche l'instance Debugger de demander une instrumentation de la couverture du code. Mais cela ne garenti pas que l'instrumentation n'est pas présente.

uncaughtExceptionHook

Soit null, soit une fonction que SpiderMonkey appelle lorsque qu'un appelle à un handler d'évènement de débug, ou fonction similaire lève une exception. On appelle ça une debugger-exception. Les exceptions levées par le Débogeur ne sont pas propagées à la cible de débogage. A la place, SpiderMonkey appelle cette fonction en lui passant debugger-exception comme seul paramètre, et l'instance Debugger comme this. Cette fonction doit retourner une valeur de reprise, qui détermine comment la cible de débogue doit continuer.

Si la fonction elle-même lève une exception,uncaught-hook-exception, SpiderMonkey lève un nouvel objet d'erreur, confess-to-debuggee-exception, à la cible de débogue avec un message qui incrimine le débogueur, et inclut des descriptions textuelles de uncaught-hook-exception et de debugger-exception d'origine.

Si uncaughtExceptionHook’s vaut null, SpiderMonkey lève une exception pour la cible de débogue, avec une message qui incrimine le débogueur, et inclut une description textuelle de debugger-exception.

Assigner une valeur non appelable et non null à cete propriété lève une exception TypeError.

(Ce n'est pas une manière idéale de gérer les bugs du débogueur, mais l'idée est que même imparfaite, une sécurité ici rend la vie plus facile aux développeurs. Par exemple une fonction d'attrapage d'exception peut accéder à des fonctionnalités du navigateur même comme la fonction alert ce que l'implémentation de cette API ne fait pas, et ainsi rend possible l'affichage des erreurs du débogueur d'une façon adaptée au contexte..)

Fonctions de gestion du Débogueur

Chaque instance Debugger hérite des propriétés d'accession, avec lesquelles il est possible de stocker des fonctions de gestion (handler functions). Afin que SpiderMonkey les appelle lorsqu'un un évènement se produit dans la cible déboguée.

Lorseque l'un des évènements ci-dessous se produit, le moteur stoppe la cible déboguée et appelle la fonction de gestion correspondante dans chaque instance Debugger liée à la cible. Les fonctions reçoivent l'instance Debugger comme valeur pour this. La plupart des fonctions de gestion peuvent retourner une valeur de reprise indiquant comme la reprise de l'exécution de la cible déboguée doit s'effectuer.

Dans une nouvelle instance de Debugger, chacune des propriétés ci-dessous est undefined par défaut. Ces valeurs ne peuvent être assignées qu’à une fonction ou undefined; Sinon une exception TypeError est levée.

Les fonctions de gestion s'exécutent dans le même thread que l'évènement qui l'a invoqué. Elles sont exécutées dans le compartiment auquel elles appartiennent et non dans un compartiment de la cible déboguée.

onNewScript(script,global)

Du code (représenté par l'instance Debugger.Script script) a été rajouté dans la portée de la cible déboguée.

La valeur de retour de cette méthode est ignorée.

onNewPromise(promise)

Un nouvel objet Promise référencé par l'instance Debugger.Object promise, a été alloué dans la portée de la cible. La pile d'allocation de la Promise peut être obtenue en utilisant la propriété promiseAllocationStack de promise.

Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre. Cepependant il est à noter qu'une valeur de reprise égale à  { return:value } est traité comme undefined (“continuer normalement”); value est ignoré.

onPromiseSettled(promise)

Un objet Promise référencé par l'instance Debugger.Object promise qui a été allouée dans la portée de la cible, a été complétée (promesse tenue ou rejetée). L'état de la Promise, sa complétion ou son rejet, ainsi que les piles d'allocation et de résolution peuvent être accédés, en utilisant les propriétés de promise.

Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre. Cepependant il est à noter qu'une valeur de reprise égale à  { return:value } est traité comme undefined (“continuer normalement”); value est ignoré.

onDebuggerStatement(frame)
Le code de la cible a exécuté une expression debugger dans frame. Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre
onEnterFrame(frame)

La pile de trame (stack frame) frame s'apprête à exécuter du code. Naturellement, frame est alors la trame visible la plus récente). Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre

SpiderMonkey n'appelle onEnterFrame que pour les trames visibles, et non-"debugger".

onExceptionUnwind(frame,value)

L'exception value a été levée, et s'est propagé à la trame has been thrown frame. frame est la trame la plus récente de la pile de trames, et est une trame de la cible. Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre. Si elle retourne undefined, l'exception continue de se propager normalement : Si le contrôle dans frame est un bloc try, le contrôle saute au block catch ou finally correspondante. Sinon, frame est supprimée et l'exception se propage a l'appelant frame.

Lorsque la propagation d'une exception cause le contrôle à entrer dasn un bloc finally, l'exception est temporairement mise de coté. Si le bloc se finit normalement, l'exception continue sa propagation, et la fonction de gestion onExceptionUnwind est appelée à nouveau, dans la même trame. L'autre possibilité est que le bloc finally sorte à cause d'une expression return, continue, ou break, ou lève une nouvelle exception. Dans ces cas, l'ancienne exception arrête sa propagation et est supprimée.

Cette fonction de gestion n'est pas appelée lors d'un retour arrière sur la trame du de possible exception over-recursion ou out-of-memory.

sourceHandler(ASuffusionOfYellow)
Cette méthode n'est jamais appelée. Si elle est appelée, une contradiction a été prouvée, et le débogueur est livre de considérer que tout est vrai.
onError(frame,report)

SpiderMonkey est sur le point de rapporter une erreur dans frame. report est un objet décrivant l'erreur avec les propriétés suivantes :

message
Le message d'erreur complètement formaté.
file
Si present, le nom du fichier source, l'URL, etc. (si cette propriété est présente alors line aussi, et vice et versa)
line
Si présent, le numéro de ligne ou l'erreur à eu lieu.
lineText
Si présent, le code source de la ligne incriminée.
offset
La position du caractère dans lineText où l'erreur se trouve.
warning
Présent et vrai s'il s'agit d'un avertissement. Absent sinon.
strict
Présent et vrai si cette erreur ou avertissement est due à la présence de l'option "strict" (à ne pas confondre avec le mode strict de EcmaScript)
exception
Présent et vrai si une exception a été levée. Absent sinon.
arguments
Un tableau de chaines de caractères, représentant les paramètres substitués dans le message d'erreur.

La valeur de retour de cette fonction de gestion est ignorée.

onNewGlobalObject(global)

un nouvel objet global global, a été crée.

Cette fonction de gestion devrait retourner une valeur de reprise spécifiant comment l'exécution doit reprendre. Cepependant il est à noter qu'une valeur de reprise égale à  { return:value } est traité comme undefined (“continuer normalement”); value est ignoré. (Autoriser la fonction à substituer sa valeur avec le nouvel objet global n'a pas l'air utile).

Cette fonction de gestion n'est disponible par les débogueurs s'exécutant dans du code privilégié (“chrome”, dans Firefox). La plupart des fonctions fournies par l'API de ce Debugger n'observent l'activité que dans les globales qui sont accessibles par l'API utilisateur, ansi cela impose cette restriction de la portée de Debugger. Cependant, la méthode onNewGlobalObject permet à l'API utilisateur de surveiller toutes les créations d'objets globaux qui se produisent n'importe où dans le système JavaScript (le “JSRuntime”, en jargon SpiderMonkey), s'affranchissant ainsi des restrictions. C'est pour cette raison que onNewGlobalObject n'est disponible que pour le code privilégié.

Fonctions du prototype de l'objet Debugger

Les fonctions décrites ci-dessous ne peuvent être appelé uniquement lorsque this fait référence à une instance value Debugger. Elles ne peuvent pas être utilisés comme méthode sur d'autres types d'objets.

addDebuggee(global)

Ajoute l'objet global désigné par global à la liste d'objets globaux que l'instance Debugger est en train de déboguer. Si la globale en question est déjà une cible de débogage, la fonction n'a pas d'effet. Retourne l'instance Debugger.Object du Debugger faisant référence à la globale en question.

La variable globale peut avoir une des valeurs suivantes :

  • Un objet global.

  • Un objet HTML5 WindowProxy (une "fenêtre extérieure" (“outer window”), en jargon Firefox), traité comme si l'objet Window du document actif du navigateur avait été passé.

  • Un wrapper cross-compartment d'un objet. Les règles ci-dessus s'appliquent à l'objet.

  • Une instance Debugger.Object appartenant à cette instance Debugger. Les règles ci-dessus s'appliquent à l'instanceréférencé.

  • Tout autre valeur est traitée comme un TypeError. (Il est à noter que chaque règle n'est appliquée qu'une seule fois lors de la résolution du paramètre global. Ainsi, par exemple, un Debugger.Object faisant référence à un second Debugger.Object qui fait référence à une gloable, ne désigne pas cette gloable du point de vue de cette fonction.)

La globale désignée par global doit être dans un compartiment différent de l'instance Debugger. Si ajouter le compartiment de la globale désignée, crée un cycle de débogueur et cible compartiment de cible de débogage, cette fonction lève une erreur.

Cette fonction retourne une instance Debugger.Object qui fait référence à l'objet global désigné.

L'instance Debugger n'a pas de référence forte sur les globales de ces cibles de débogue. Si une globale n'est plus atteignable, alors elle est supprimée des cibles de débogue.(Naturellement, l'instance Debugger.Object que retourne cette méthode n'est pas une référence forte sur la globale ajoutée.)

Si ce débogueur traque les sites d'allocations et ne peut pas le faire pour global cette fonction lève une Error.

addAllGlobalsAsDebuggees()

Cette fonction est semblable à addDebuggee, mais ajoute tous les objets globaux de tous les compartiments des cibles de débogage de l'instance Debugger.

Si ce débogueur traque les sites d'allocations et ne peut pas le faire pour unes des globales, cette fonction lève une Error. Sinon cette fonction retourne undefined.

Cette fonction de gestion n'est disponible par les débogueurs s'exécutant dans du code privilégié (“chrome”, dans Firefox). La plupart des fonctions fournies par l'API de ce Debugger n'observent l'activité que dans les globales qui sont accessibles par l'API utilisateur, ansi cela impose cette restriction de la portée de Debugger. Cependant, la méthode addAllGlobalsAsDebuggees permet à l'API utilisateur de surveiller toutes les créations d'objets globaux qui se produisent n'importe où dans le système JavaScript (le “JSRuntime”, en jargon SpiderMonkey), s'affranchissant ainsi des restrictions. C'est pour cette raison que addAllGlobalsAsDebuggees n'est disponible que pour le code privilégié.

removeDebuggee(global)

Supprime l'objet global désigné par global de la liste des cibles de débogue de l'instance Debugger. Retourne undefined.

Cette méthode interprète global en utilisant les mêmes règles que addDebuggee.

Supprimer une globale d'un cible de Debugger supprime tous les points d'arrêt qui appartiennent à ce Debugger dans cette globale.

removeAllDebuggees()
Supprime tous les objets globaux de la liste des cibles de débogue de l'instance Debugger. Retourne undefined.
hasDebuggee(global)

Retourne true si la globale désignée par global est une cible de débogue de l'instance Debugger.

Cette méthode interprète global en utilisant les mêmes règles que addDebuggee.

getDebuggees()

Retourne un tableau d'instances uniques de Debugger.Object dont les références sont toutes des cibles de débogue de l'instance Debugger.

Vu que les instances Debugger n'ont pas de références fortes sur les globales des cibles de débogue, si une globale n'est plus ateignable, elle peut être supprimée à tout moment du tableau que cette méthode retourne.

getNewestFrame()
Retourne une instance Debugger.Frame faisant référence à la trame visible la plus récente sur la pile d'appel du thread, ou null si il n'y a pas de trames visibles sur la pile.
findSources([query])(not yet implemented)

Retourne un tableau de toutes les instances Debugger.Source qui correspondent à query. Chaque source apparait exactement une fois et une fois seulement dans le tableau. query est un objet dont les propriétés restreignent les sources retournées. Une source doit correspondre à tous les critères donnés par query pour pouvoir être retournée. Si query n'est pas passé, toutes les sources des scripts des cibles  de débogue seront retournées.

query peut avoir les propriétés suivantes :

url
L'url de la source doit être égale à la valeur de cette propriété.
global
La source doit avoir été évaluée dans la portée de l'objet global donné. Si cette propriété vaut une instance Debugger.Object appartenant à l'instance Debugger alors son référent est utilisé. Si l'objet n'est pas un objet global, alors la globale de la portée ou elle a été allouée est utilisée.

Il est à noter que le résultat peut inclure des sources qui ne peuvent plus être utilisées par la cible déboguée. Par exemple, du code évalué qui a fini son exécution, ou une source pour des fonctions non atteignables. La présence ou l'absence de ces sources peuvent dépendre du comportement du Ramasse-miettes (Garbage Collector), donc les résultats de cette fonction ne sont pas complètement déterministes.

findScripts([query])

Retourne un tableau d'instances de Debugger.Script pour tous les scripts des cibles de débogue qui correspondent à query. Chaque instance n'apparait qu'une seule fois dans le tableau. query est un objet dont les propriétés restreignent les scripts retournés. Chaque script doit correspondre à tous les critères de query pour être retourné. Si query n'est pas renseigné, alors le tableau contiendra les instances Debugger.Script de chaque script de la cible.

query peut avoir les propriétés suivantes :

url
L'url de la source doit être égale à la valeur de cette propriété.
source
La propriété source du script doit être égale à la valeur de cette propriété.
line
Le script doit au moins partiellement couvrir la ligne source donnée. Si cette propriété est présente alors url doit l'être aussi.
column
Le script doit inclure la colonne donnée à la ligne spécifiée par la propriété line. Si cette propriété est présente, alors  url et line doivent l'être aussi.
innermost
Si cette propriété est présente et vaut true, le script doit être le script le plus profond couvrant l'emplacement de source donnée. Les scripts de code renfermant du code sont omis.
global
La source doit avoir été évaluée dans la portée de l'objet global donné. Si cette propriété vaut une instance Debugger.Object appartenant à l'instance Debugger alors son référent est utilisé. Si l'objet n'est pas un objet global, alors la globale de la portée ou elle a été allouée est utilisée.

Toutes les propriétés de query sont optionnelles. Passer un objet vider retourne tous les scripts de la cible.

Il est à noter que le résultat peut inclure des instances Debugger.Script de scripts qui ne peuvent plus être utilisés par la cible déboguée. Par exemple, du code évalué qui a fini son exécution, ou une source pour des fonctions non atteignables. La présence ou l'absence de ces sources peuvent dépendre du comportement du Ramasse-miettes (Garbage Collector), donc les résultats de cette fonction ne sont pas complètement déterministes.

findObjects([query])

Retourne un tableau d'instances de Debugger.Objet pour tous les objets alloués dans la portée des globales de la cible déboguée qui correspondent à query. Chaque instance n'apparait qu'une seule fois dans le tableau. query est un objet dont les propriétés restreignent les scripts retournés. Chaque objet doit correspondre à tous les critères de query pour être retourné. Si query n'est pas renseigné, alors le tableau contiendra les instances Debugger.Objet de chaque objet alloué dans la portée des globales de la cible.

query peut avoir les propriétés suivantes :

class
Si présente, seulement les objets dont le nom de la [[Class]] interne correspondent à la chaine de caractères donnée seront retournés. Il est à noter que dans certains cas l'objet prototype pour un constructeur donné a la même [[Class]] vu que des instances y font référence, mais ne peuvent pas être elle-même des instances de cette classe. Du code récupérant les objets par nom de classe devrait donc examiner plus en détail le retour avant d'essayer de les utiliser.

Toutes les propriétés de query sont optionnelles. Passer un objet vider retourne tous les scripts de la cible.

Contrairement à findScripts, cette fonction est déterministe, et ne retournera jamais de Debugger.Objects faisant référence à des objets non atteignables qui ne sont pas encore collectés par le ramasse-mièttes.

clearBreakpoint(handler)
Enleve tous les points d'arrêt mis dans l'instance Debugger qui utilisent handler comme son handler. Il est à noter que les points d'arrêt utiliser d'autres handlers mais au même emplacement eux restent en place.
clearAllBreakpoints()
Enleve tous les points d'arrêt mis dans l'instance Debugger.
findAllGlobals()

Retourne un tableau d'instances de Debugger.Objet pour tous les objets alloués présents dans cette instance JavaScript.

Les résultats de cet appel peut être affecté de différentes façons non déterministes, du aux détails de l'implémentation JavaScript. Le tableau peut inclure des instances Debugger.Object faisant référence ) des objets globaux qui ne sont pas atteignables par la cible déboguée. (Naturallement, une fois que la fonction est exécutée, les instances Debugger.Object retournés fait une référence forte aux globales.

Cette fonction de gestion n'est disponible par les débogueurs s'exécutant dans du code privilégié (“chrome”, dans Firefox). La plupart des fonctions fournies par l'API de ce Debugger n'observent l'activité que dans les globales qui sont accessibles par l'API utilisateur, ansi cela impose cette restriction de la portée de Debugger. Cependant, la méthode findAllGlobals permet à l'API utilisateur de surveiller toutes les créations d'objets globaux qui se produisent n'importe où dans le système JavaScript (le “JSRuntime”, en jargon SpiderMonkey), s'affranchissant ainsi des restrictions. C'est pour cette raison que findAllGlobals n'est disponible que pour le code privilégié.

makeGlobalObjectReference(global)
Retourne les Debugger.Object qui font référence a l'objet global désigné par global, sans ajouter la globale en question à la cible de débogue. Si global ne désigne pas un objet global, la fonction lève une exception TypeError. Cett fonction détermine quelle globale est désignée global en utilisant la même règle que using Debugger.prototype.addDebuggee.
adoptDebuggeeValue(value)

Retourne une valeur de cible de débogue appartenant à ce Debugger, équivalent à la valeur de cible de débogue value.

Si value est une valeure primitive, la fonction retourne la valeur non-changé. Si la valeur est un Debugger.Object appartenant à un Debugger arbitraire, retourne un équivalent Debugger.Object appartenant à ce Debugger. Sinon, si la value est un autre type d'objet, et donc pas une valeur de cible de débogue, la fonction lève une erreur TypeError.

Méthodes statiquesde l'objet Debugger

Les fonctions décrites ci-dessous ne sont pas avec la valeur this.

isCompilableUnit(source)
La chaine de caractère donné par source, retourne false si la chaine est une expression JavaScript qui pourrait être valide avec l'ajout d'autres lignes. Sinon retourne true. L'idée est d'accumuler les lignes dans un buffer jusqu'a ce que la fonction retourne ture et seulement alors, passer le buffer au compileur.

Source Metadata

Generated from file:
 
js/src/doc/Debugger/Debugger.md
Watermark:
sha256:03b36132885e046a5f213130ba22b1139b473770f7324b842483c09ab7665f7c
Changeset:
e91b2c85aacd

Étiquettes et contributeurs liés au document

Contributeurs à cette page : wbamberg, maximelore
Dernière mise à jour par : wbamberg,