Compiling Nodes as Console Applications

Under this topic we discuss details and technical differences between creating your uniGUI Nodes as console applications vs. creating them as desktop (GUI) applications.

Windows GUI Applications

These applications are designed to run as GUI desktop applications with one or several forms. All Delphi VCL applications are in this category.

All uniGUI applications that are created as Standalone Server project are also Windows GUI applications.

See also: Standalone Server

Windows Console Applications

These applications usually don't deploy forms. They come with a console window which is used to interact with the user through a command line prompt. All uniGUI applications that are created as Standalone Server (Console Application) are technically Windows Console applications.

What are the differences?

If you are using Standalone Server for debugging purposes or deployment on desktop, there are no major differences between them. You can create your application either as Standalone Server Project or Standalone Server (Console Application) and you will get the same results.

Deployment as HyperServer Nodes

Standalone Servers are also used for deployment as HyperServer Nodes. If you plan to run your applications under uniGUI HyperServer you must create and run them as Standalone Server applications.

In this case there is a major difference between creating your application as Windows GUI application or Windows Console application. To better understand this, first we need to become familiar with Windows Desktop Heap.

Windows Desktop Heap

Desktop Heap is a memory space which Windows uses to store various UI objects. This is a limited memory space which is available on a per-session basis where a session represents a single user’s logon environment. When a new executable is launched a certain amount of this heap space is reserved/occupied for this new executable. Logically, this limits the maximum number of executable apps that may be launched for a session. When this limit is reached Windows will refuse to launch more apps and silently terminates apps before they become active, leaving an error log entry in Windows Event Viewer application logs.

Desktop apps consume considerably more space from Windows Desktop Heap compared with console apps. That means the maximum number of apps that may run simultaneously will be lower if they are compiled as desktop apps. On the other hand, this number increases significantly if the same apps are compiled as console applications.

There is no exact documented number of bytes consumed from the Desktop Heap per process, but tests indicate that even the most basic uniGUI app compiled as a desktop app will reach the Desktop Heap limit after a few hundred instances. Applications compiled as console apps are not affected by the Desktop Heap limit; their maximum number is primarily limited by available physical memory. In an extreme test more than 10,000 console apps (HyperServer Nodes) were launched on a system with 64 GB RAM, demonstrating that console apps avoid the Desktop Heap limitation.

See also: Desktop Heap Overview

How this relates to uniGUI HyperServer

uniGUI HyperServer launches multiple instances of the same uniGUI application called Nodes. Because Windows Desktop Heap limits the number of subprocesses that can be launched under a Windows session, to maximize scalability you should create your uniGUI apps as console applications (or convert existing ones) so the Desktop Heap limit will not be reached.

See also: Maximizing HyperServer Scalability

Converting existing Standalone Server apps to Console Apps

If you want to convert existing standalone server apps to console apps, follow the procedures for your development environment.

1

Delphi

For a Delphi project the only difference between a uniGUI standalone desktop server app and a console server app is the APPTYPE compiler directive:

Add the directive {$APPTYPE CONSOLE} to your .dpr file and rebuild your application.

Example:

Project1.dpr

program Project1;

{$APPTYPE CONSOLE}

uses
  Forms,
  ServerModule in 'ServerModule.pas' {UniServerModule: TUniGUIServerModule},
  MainModule in 'MainModule.pas' {UniMainModule: TUniGUIMainModule},
  Main in 'Main.pas' {MainForm: TUniForm};

{$R *.res}

begin
  ReportMemoryLeaksOnShutdown := True;
  Application.Initialize;
  TUniServerModule.Create(Application);
  Application.Run;
end.

Adding the compiler directive and rebuilding is sufficient to convert a standalone app to a console application.

2

C++ Builder

Converting a C++ Builder desktop app to a console app is less straightforward than in Delphi. You can either create a new console app and move your forms and modules into it, or edit your project CPP file and make the necessary modifications.

Typical changes include:

• Change the Windows main procedure from: int WINAPI_tWinMain(HINSTANCE, HINSTANCE, LPSTR, int) to: int_tmain(int argc, _TCHAR* argv[])

• Add the header <tchar.h> if missing.

Example project file:

Project1.cpp

//---------------------------------------------------------------------------
#include <vcl.h>
#pragma hdrstop
#include <tchar.h>
#include <UniGUIVars.hpp>

USEFORM("ServerModule.cpp", UniServerModule); /* TUniGUIServerModule: File Type */
USEFORM("MainModule.cpp", UniMainModule);     /* TUniGUIMainModule: File Type */
USEFORM("Main.cpp", MainForm);                /* TUniForm: File Type */
//---------------------------------------------------------------------------

#ifdef _WIN64
#pragma link "UniGUIVars.o"
#else
#pragma link "UniGUIVars.obj"
#endif

#pragma Project1
//---------------------------------------------------------------------------

int_tmain(int argc, _TCHAR* argv[])
{
  ReportMemoryLeaksOnShutdown = true;
  try
  {
    Forms::Application->Initialize();
    Uniguivars::CreateServerModule(__classid(TUniServerModule));
    Forms::Application->Run();
  }
  catch(Exception &exception)
  {
  }
  return 0;
}
//---------------------------------------------------------------------------

These changes should suffice to make the conversion, though creating a new console project and moving units/forms can sometimes be easier depending on project complexity.