What does it mean to run a procedure as SINGLETON or SINGLE-RUN?

How are these two modes alike, and how do they differ?

How are singleton and single-run procedures like persistent procedures, and how are they different?

 

 

The SINGLETON and SINGLE-RUN options were added to the ABL RUN statement in OpenEdge 11.2. Like the PERSISTENT option, SINGLETON and SINGLE-RUN allow a single instance of a module (a procedure or in some cases a class) to be invoked multiple times through various entry points (internal procedures, user defined functions or in some cases class methods). They may be run on an AppServer or locally through the SESSION handle. However, singleton and single-run procedures differ from each other and from persistent procedures in important ways:

• Neither RUN SINGLETON nor RUN SINGLE-RUN statements initially run the module. The RUN statement performs some initialization, but the object is not instantiated until an entry point in the module is invoked.
• Singleton modules remain instantiated after they are run; single-run modules are instantiated only when an internal procedure or user-defined function that they define is invoked remotely, and are deleted when the internal procedure or user-defined function completes.
• Neither singleton nor single-run bind to a particular AppServer agent. This makes them particularly useful for state-free AppServers.
• If a singleton is already instantiated when the client invokes it again, the existing instantiation is used. A single-run procedure will never be in this situation, because it was deleted when the previous module completed; therefore it will always need to be instantiated again when the client invokes it again.
• Each time an internal procedure or user-defined function of a single-run procedure is called, a new instance of its procedure context is created which exists only during the execution of the internal procedure or user-defined function. All of its data, buffers, and widgets are duplicated and separately managed by the new instantiation until the procedure instance is deleted.
• A singleton does not go out of scope when one of its internal procedures, functions or methods returns. However, do not rely on a singleton running on an AppServer for state or context, because each agent will have a separate copy of the singleton and the client could connect to any agent on any call. A single run procedure is completely deleted when one of its internal procedures returns, so it goes out of scope at that time.
• All clients access the same singleton, no matter how many client programs "instantiate" it in their code. Each client instantiates its own single-run procedure every time it invokes an internal procedure; any other clients invoking the same internal procedure have already deleted their instances.
• A singleton holds share locks after the procedure returns, until the singleton is deleted. A single-run procedure is deleted at each return, so any share locks it holds are released at that time.
• The ASYNCHRONOUS option cannot be used with either the SINGLE-RUN or SINGLETON option when instantiating an external procedure. However internal procedures of a SINGLETON procedure may be run asynchronously using the syntax "RUN internal_procedure IN proc-handle. . . ASYNCHRONOUS".
• Modules may be invoked as singleton or single-run in REST services. The mode is specified in the REST main annotation. Either internal procedures or class methods may be invoked in singleton mode, but only internal procedures may be invoked in single-run mode.
• Both singleton and single-run procedures conserve network resources compared to persistent procedures. The handles they create and delete on the client side are only proxy handles. The object on the server is not created until an internal procedure or method is actually invoked. It is deleted on the server (automatically by the AVM for single-run, or by server-side ABL code for singleton). If the client executes a sequence like "create procedure -- run internal procedure or method on the handle -- delete procedure", this translates to one network round trip rather than three.

The following table summarizes the similarities and differences between singleton, single-run and persistent procedures:

	Singleton	Single-Run	Persistent
Procedure run when invoked?	No	No	Yes
Procedure remains instantiated after it is run?	Yes	No	Yes
RUN statement binds client to AppServer agent?	No	No	Yes
Can instantiate multiple copies?	No; subsequent RUN statements use the existing instance	No; each instance is deleted after the internal procedure or function completes	Yes
Need to delete procedure?	Yes (on server)	No (happens automatically on each entry point invocation)	Yes (delete from client)
Network round trips	One per entry point invocation (minimum of one)	One per entry point invocation (minimum of one)	One to instantiate + one per entry point invocation + one to delete (minimum of three)
How long does procedure context exist (data, buffers, widgets,etc.)?	Until procedure is deleted	Until entry point invocation returns (new copies created for each invocation)	Until procedure is deleted, except  static widgets are destroyed when invocation returns
How long are share locks held?	Until procedure is deleted	When entry point invocation returns	Until procedure is deleted
Is same instance invoked by more than one client?	Yes	No (instance recreated for each invocation)	No
Run asynchronously?	Yes (ASYNCHRONOUS option on internal procedure call)	No	Yes
Can be invoked from REST service?	Yes (internal procedures and class methods)	Yes (internal procedures only)	No
Best for AppServer operating mode...	Stateless or state-free	Stateless or state-free	State-aware
Think of this mode as...	"Only one"	"One at a time"	"One or maybe more"

References to Other Documentation:

https://documentation.progress.com/output/ua/OpenEdge_latest/index.html#page/pasoe-migrate-develop/persistent,-single-run,-and-singleton-attributes.html
https://documentation.progress.com/output/ua/OpenEdge_latest/index.html#page/dvref/run-statement.html