diff --git a/doc/design/scope.md b/doc/design/scope.md index 8d5744c227b70bffd7025badb4f7e9e1d5a401c4..f2869bc254acba6e4571ad723aefbfc51562f56d 100644 --- a/doc/design/scope.md +++ b/doc/design/scope.md @@ -2,22 +2,42 @@ ## Overview -预期使用场景。 +Scope is an important concept in programming languages, which defines a program region that a set of bindings between names and entities applies. In a specific scope, a valid name is uniquely associated with an entity, such as a variable. And in another scope, this name may refer to other entity or nothing at all. It clearly restricts the visibility and validity of names in a program. Hence **Scope** is introduced to PaddlePaddle to manage variables in context. But different from the original abstract concept, Scope now becomes an object with two important attributes: + +- Scope is an association of a name to variable. +- Variables in a parent scope can be retrieved from local scope. + +A detailed explanation of these two attributes goes as following. -引出Scope的两个属性。 - 1. Scope是Variable的Container - 2. Scope可以共享 ## Scope is a Container of Variables. - * Scope contains Variables as it's data member. - * Scope contains methods that are used to manage Variables, such as Create/Get/Delete. - * every variable only belong to one certain Scope. - * Scope should destruct all Variables within it when itself is destructed. - * Variable can only be created by Scope. - * Variable can only be got from Scope. +Scope is used to provide a running environment for Net. + +1. Scope mainly has Variables as it's data member. + + Scope is a running environment for Net. Net should get all it need to do computation from a scope, such as data buffer, state(momentum) etc. + All these data/state can be abstracted and create as variable in Paddle, so the only thing Scope need to care about is Variable. +1. Variable can only be created by Scope. +1. Variable can only be got from Scope. +1. Scope contains methods that are used to manage Variables, such as Create/Get/Delete. + + Because we only need to care about Variable, we only need method to manage the lifecycle of Variable. + - `Create` is used to create a Variable by its name and add the mapping relation. + - `Get` is used to find a Variable by name. + - `Delete` is used to remove a Variable because sometimes we want to release memory or other resources. + +1. Every variable only belongs to one certain Scope. + + Variable can not be shared between scopes, if we want to use variables from different scope we can use `Parent scope`. + +1. Scope should destruct all Variables within it when itself is destructed. + + Because Variable can only be got from Scope, when destroying Scope, we also need to destroy all the Vars in it. + +1. Scope do not contain Operators and have no information to run them. - * Scope do not contains Operators and have no information to run them. + Net is designed to drive the computation, Scope is only used to provide a running environment. ```cpp class Scope {