FWD » Core Development » Base Language

CREATE WIDGET-POOL, DELETE WIDGET-POOL and any scoping of resources

From the documentation and some testing, it seems that scoping is done on the nearest executing block; we should be able to implement the scoping using a Scopeable instance registered with the TransactionManager for scope notifications, without any other scope-related code required in the generated sources.

There is already a WidgetPool class added in the p2j.ui package - this will be moved to p2j.util. More, anyone who implements CREATE statements which accept a IN WIDGET-POOL clause, should provide support for this clause.

It seems like there are 4 kinds of pools:

- un-named session pool (created automatically by the 4GL and used as the default pool)
- un-named scoped pool that attaches to the nearest enclosing procedure or method
- named global pool (whose lifetime is scoped to the creating procedure)
- named global persistent pool (must be deleted explicitly, it outlives its creating procedure)

I have these general questions about widget-pools:

1. Do we need to implement a global unnamed widget-pool like Progress does? This would ensure that "proper" deletes occur on every resource that is not created in a scoped or named pool.

2. Which dynamic/handle resources are created in widget-pools?

3. What changes do we need to make to those resources to properly "register" with their pool? I assume we need a scoped dictionary to find the correct pool. Plus we will have to support using a named pool.

4. What happens to a resource when it is in use and gets deleted. For example, a dynamic button can have a CHOOSE trigger that deletes the button (or even the entire pool it resides in). What happens to the UI in that case?

5. Is the only real behavior here all about doing an "implicit" DELETE OBJECT based on leaving a particular scope? I see no other functional behavior based on the documentation.

6. Do unnamed widget pools scope to all top-level blocks (e.g. triggers, functions)?

7. Is it correct that a locally scoped unnamed pool superseded within the same procedure by calling another internal procedure that creates its own unnamed pool?

8. Is it correct that an unnamed scoped pool that is associated with a persistent procedure will be used for internal procedures called on that proc handle, even if other widget pools are on the call stack (e.g. the caller is outside of the persistent proc and has its own widget pool)?

9. Does a named pool really get deleted when the procedure that created it exits? If so, what is the value of using this?

I'll look at your code next.

Code feedback:

1. The WidgetPool.create/delete methods need variants for character expressions.
2. Perhaps I missed it, but I don't see the support for converting PERSISTENT into a boolean true.

Otherwise it looks good.

One other thought: in regard to issues 6 and 8 above, they imply that each new top-level scope needs to have a "registration target" which is the widget-pool to which newly created resources get added.

1. Do we need to implement a global unnamed widget-pool like Progress does? This would ensure that "proper" deletes occur on every resource that is not created in a scoped or named pool.

At this time, I can't find any scoping-related differences between unnamed and named widget-pools. Both seem to behave the same. See question 7 for more details.

2. Which dynamic/handle resources are created in widget-pools?

The following CREATE statements accept an IN WIDGET-POOL clause. Thus, I think these are the only statements which can create resources and add them to widget-pools. Testing other statements (like CREATE SERVER and CREATE SOCKET) shows that the resource is not added to the pool.

CREATE BROWSE
CREATE BUFFER
CREATE CALL
CREATE DATASET
CREATE DATA-SOURCE
CREATE QUERY
CREATE SAX-ATTRIBUTES
CREATE SAX-READER
CREATE SAX-WRITER
CREATE SOAP-HEADER
CREATE SOAP-HEADER-ENTRYREF
CREATE TEMP-TABLE handle
CREATE { BUTTON     | COMBO-BOX | CONTROL-FRAME | DIALOG-BOX     |
         EDITOR     | FILL-IN   | FRAME         | IMAGE          |
         MENU-ITEM  | RADIO-SET | RECTANGLE     | SELECTION-LIST |
         MENU       | SLIDER    | SUB-MENU      | TEXT           |
         TOGGLE-BOX | WINDOW    | VALUE ( string-expression )
       }
CREATE X-DOCUMENT
CREATE X-NODEREF

3. What changes do we need to make to those resources to properly "register" with their pool? I assume we need a scoped dictionary to find the correct pool. Plus we will have to support using a named pool.

If an unnamed pool is in effect, the CREATE statements which accept the IN WIDGET-POOL clause (and don't have the clause) will register the resource with the unnamed pool. Thus, conversion rules for the CREATE statements with an IN WIDGET-POOL clause will have to emit the widget-pool's name, if available. Also, the runtime will need to register the resource with the appropriate pool (named or unnamed).

4. What happens to a resource when it is in use and gets deleted. For example, a dynamic button can have a CHOOSE trigger that deletes the button (or even the entire pool it resides in). What happens to the UI in that case?

The resource can be deleted using DELETE OBJECT (with no reported errors) and in case of a UI resource, the UI gets updated by removing the widget from the screen (immediately in case of triggers). Same for deleting a widget-pool - all contained resources get deleted (same for UI as with delete object).

5. Is the only real behavior here all about doing an "implicit" DELETE OBJECT based on leaving a particular scope? I see no other functional behavior based on the documentation.

Yes, this is what I found too - DELETE OBJECT is used to delete the resources when the widget-pool gets deleted.

6. Do unnamed widget pools scope to all top-level blocks (e.g. triggers, functions)?

See answer for question 9.

7. Is it correct that a locally scoped unnamed pool superseded within the same procedure by calling another internal procedure that creates its own unnamed pool?

If the external procedure, internal procedure proc0 and internal procedure proc1 create their own unnamed pools, like:

def var h as handle.
procedure proc0.
   create widget-pool.
   create button h.
   message valid-hande(h). /* shows yes */
end.

procedure proc1.
   create widget-pool.
   run proc0.
   message valid-hande(h). /* shows no */
end.

run proc1.
message valid-handle(h). /* shows no */

def var h as handle.
def var h2 as handle.
def var h3 as handle.

procedure proc0.
   create widget-pool persistent.
   create button h.
   message valid-hande(h). /* shows yes */
end.

procedure proc1.
   create widget-pool.
   create button h2.
   run proc0.
   create button h3.
   message valid-hande(h) valid-handle(h2) valid-handle(h3). /* shows yes yes yes */
end.

run proc1.
message valid-hande(h) valid-handle(h2) valid-handle(h3). /* shows yes no yes */

8. Is it correct that an unnamed scoped pool that is associated with a persistent procedure will be used for internal procedures called on that proc handle, even if other widget pools are on the call stack (e.g. the caller is outside of the persistent proc and has its own widget pool)?

When RUN ... PERSISTENT is used, the named/unnamed pools are not deleted (I guess they will be alive for the duration of the persistent procedure). For your specific case, I think you are correct, as when the persistent procedure is deleted, the resource is gone too (thus it must have been created in the persistent proc's unnamed pool).

9. Does a named pool really get deleted when the procedure that created it exits? If so, what is the value of using this?

Yes, it does get deleted, unless is the pool or the procedure is PERSISTENT.

If we have these programs:

/*wp1.p*/
def new shared var h as handle.
def new shared var fh as handle.
def var i as int.

form i with frame f1.
fh = frame f1:handle.
run wp2.p.
message valid-handle(h).

/*wp2.p*/
def shared var h as handle.
def shared var fh as handle.

message "1-named pool, 2-unnamed pool, 3-no pool, 4-named persistent, 5-unnamed persistent " update i as int.

if i = 1 then do:
  create widget-pool "pp".
  create button h in widget-pool "pp" assign label="bla1" visible=true row=3 col=3 frame=fh.
end.
if i = 2 then do:
  create widget-pool.
  create button h assign label="bla1" visible=true row=3 col=3 frame=fh.
end.
if i = 3 then do:
  create button h assign label="bla1" visible=true row=3 col=3 frame=fh.
end.
if i = 4 then do:
  create widget-pool "pp" persistent.
  create button h in widget-pool "pp" assign label="bla1" visible=true row=3 col=3 frame=fh.
end.
if i = 5 then do:
  create widget-pool persistent.
  create button h  assign label="bla1" visible=true row=3 col=3 frame=fh.
end.

message valid-handle(h).

• when working with widget-pools, it is important to run the program from the command line, else the editor will cache the persistentwidget-pools and will lead you on a wrong path.
• when creating the unnamed pool, multiple CREATE WIDGET-POOL calls in a row will have no effect. The following code:
  

  def var h as handle.
  procedure proc0.
     create widget-pool persistent.
     create button h.
  end.
  
  run proc0.
  message valid-handle(h). /* shows yes */
  create widget-pool persistent.
  message valid-handle(h). /* shows yes */
  

  
  will not alter the pooled resources, even if another CREATE WIDGET-POOL statement is executed.
• When attempting to create a named pool, if already exists a pool with the given name, then ERROR condition is raised and this message is shown:
  

  Attempt to create widget-pool <name>, but it already exists. (4116)
  

• when deleting the unnamed widget pool, no error appears if there is no active unnamed widget pool.
• when deleting the named widget pool, the following error is shown if the widget-pool does not exist:
  

  Attempt to delete widget-pool <name>, but it doesn't exist. (4117)
  # 

Regression testing for the conversion support update has passed, applied to bzr revision 10162.

Should the runtime task include working on the resources which can be added in a pool or add just the pooling support and let the registration of the resources with the pool be added when the resource is implemented?

My approach would be to add pooling support only for the resources which are currently fully-implemented (like widgets) and for the others, add the registration when the resource is implemented. Also, first I would provide basic stubs for resource pooling (for named and unnamed), to let the people implementing the resource be able to add the registration code, even if pooling is not ready yet.

The estimated time seems accurate, assuming not all poolable resources need to be touched/tested.

Code Review 0919a

Overall, it looks very good.

1. Why throw IllegalStateException in WidgetPool.addResource()?

2. Why does WidgetPool.newPool() have an unnamed boolean flag if name == null can be used to detect if this should be unnamed?

3. WidgetPool.getPool(String name, boolean currentScope) may be better named as findActivePool() to make it clear that there is a scope-based search going on.

4. Do we need code to do a final cleanup/removal of unnamed persistent pools when the user's session exits?

5. Where do we create the initial unnamed widget pool (that is implicitly persistent)?

6. Please enhance the class javadoc to address the following:

1. What exactly is the purpose of a widget-pool? If I understand correctly, it is a mechanism to explicitly define the scope at which resources get an "implicit" DELETE OBJECT when the control flow causes the program to exit that particular scope. At its most basic, a widget pool is just a list of resources that get deleted, an optional name, an optional persistent flag and an association with a block scope at exists at a "top-level" block (external proc, internal proc, user-defined function and trigger).
2. By its very nature, this only affects resources that are dynamically created (and thus must be removed using DELETE).
3. Which resources have widget-pool support in the 4GL?
4. It should be made clear (also in the scopeStart() and scopeFinished() javadoc) that the scopes only open and close at top-level blocks. Inner blocks don't cause any scoping behavior.
5. All widget-pool behavior is context-local. In other words, it is specific to the current user's session.
6. Resources can only ever exist in one pool.
7. New widget-pools are created in the 4GL in which cases? If I understand correctly, 1 unnamed is created by default when the session starts and then every time CREATE WIDGET-POOL is called a new one is added.
8. How many unnamed persistent pools can be created? (1 by default and then 1 more explicitly per external proc?)
9. How do unnamed persistent pools ever get deleted? It seems like they will always get leaked upward in the scopes and can't ever be deleted.

The changes are really good. The class javadoc improvements are excellent!

The exception is thrown because this method must always find the pool, when a named pool is specified. The exception will be thrown only if someone forgets to validate the pool before adding the resource to the pool, and the named pool doesn't exist. This is needed because the pool must be validated first, before resource-related validation (like buffer name for CREATE BUFFER statement)

If I understand correctly, you are saying that it would be a P2J error for this to occur. If so, please document this in comments in this method.

4. Do we need code to do a final cleanup/removal of unnamed persistent pools when the user's session exits?

From the list of resources which can be pooled, the only one which links it to an external dependency is the temp-table. But this one is already context-local, so will be discarded when the session ends. So as the resources already get discarded (and they should clean too) when the user's session exits, the pool doesn't need to clean up after them.

My concern here is that the fact that the current implementation of these resources is safe cannot be easily determined by reading the code. Please some javadoc to explain that:

No session-level widget-pool cleanup is implemented at this time. The current implementation of all the poolable resources does not require any session-level cleanup processing that is driven by widget pools. Should the implementation of any one of the poolable resources be modified to be dependent upon session-level widget-pool cleanup, then this feature will have to be added.

After adding the comments, you can check in and distribute the update without further testing. The changes should be safe.