How vely works

Creating an application

A Vely application <app name> is created by an application owner, i.e. an Operating System user who will own its processes and data, by using vf, such as for example:

sudo vf -i -u $(whoami) <app name>

This will create directory structure described here. Vely application can be used as a FastCGI server, a command_line program or a CGI program. Note that vf is the only Vely utility requiring sudo privileges, and only for application creation.

How Vely works

In a single step, Vely code (.v files) is precompiled entirely into C, linked, and ready to run as a command-line program or as an application server, or both. Error reporting is based on Vely source code (.v files), though you can specify generated code lines to be used.

vv will preprocess .v source files and generate C code for supported language_constructs (database, file, strings etc.). Then, vv builds both a command-line program and a FastCGI application server executable for application <app name> (if not specified, <app name> is the directory name where source code is located). Executables created are located in directory:

/var/lib/vv/bld/<app name>

A FastCGI application runs as a daemon, i.e. it runs in the background and does not exit, serving incoming requests. Typically, a number of FastCGI processes are started to serve incoming processes in parallel; in adaptive mode, the number of processes running may vary according to the load - including zero running processes for near-zero memory usage.

A command-line program works exactly the same way as a FastCGI application; it takes the same input and produces the same output.

.v files and requests

Files with the .v extension are Vely source files. You must have at least one Vely source file (.v file). If a Vely source file starts with an underscore, it is a non_request file, which can implement anything; otherwise it is a request file. A request file implements a request handler, which handles a URL query sent by the client (such as reverse proxies like Apache or Nginx) or provided to command-line program via environment variables.

To specify the request handler in the URL, use "req" input parameter. A request handler must implement a function named after the base name of .v file. For example, in a URL query such as:

req=add_stock&ticker=ABC&price=130

the request handler must be implemented as function

void add_stock() {...}

in file add_stock.v.

This correlation between requests and file names makes it easy to find the code you want and to maintain it. Vely will generate the code that will automatically route input requests to the appropriate code based on the "req" input parameter - for example a request like

http://<yourwebsite>/<your_app>?req=some_request&par1=val1&par2=val2

will automatically invoke function some_request() implemented in file "some_request.v" with input parameters "par1" and "par2" (and their values) available via input-param construct.

Not every source code file was meant to handle a request. You might have a number of non-request files that implement other code, such as commonly used functions. Such files are non-request source code and their names must start with underscore ("_"). For example, file "_display_table.v" might implement a common HTML table displaying code. Functions and methods in the support code files can be named in any fashion.

Some non-request source files have predefined meaning: "_startup.v" (startup_handler), "_before.v" (before_request_handler) and "_after.v" (after_request_handler).

Vely builds an application by looking at .v files present in the current directory. Therefore you don't have to specify what source code your application uses - all .v files will be automatically picked up and compiled, and request handlers (those .v files that do not start with an underscore) are used to generate vely_dispatch_request.v file, which is a request-dispatcher. Thus, it is easy to view at a glance what kind of requests an application serves and what is its general purpose.

You can see the default implementations for all auto-generated files in directory

/var/lib/vv/bld/<app name>

Directories and files

While you can keep and compile Vely source files in any directory, the directories used by Vely are always under /var/lib/vv directory. A Vely application is always owned by a single Operating System user, while different applications can be owned by different users. This is the directory structure:

• /var/lib/vv/bld/<app name>
  Build directory is where your FastCGI application executable is built, with name <app name>.fcgi. The command-line executable is named <app name>. This is a scratch-pad directory, so do not alter files in it, or use for anything else.
  
  
• /var/lib/vv/<app name>
  Application directory. All application data, including internals such as sockets, are kept here. Each such directory is owned by its owner with 700 privileges, preventing other users from accessing its files.
  
  
• /var/lib/vv/<app name>/app
  Application home directory. This is the current working directory when your application runs. Copy here any files and directories your application needs.
  
  
• /var/lib/vv/<app name>/app/file
  file_storage used for uploads and new document creation. Do not write there directly; Vely does that for you, such as with uniq-file for instance.
  
  
• /var/lib/vv/<app name>/app/trace
  When tracing is enabled, process tracing is written in per-process files if enabled with --trace option (see vv). Note that a special file "backtrace" is appended to when program crashes (or report-error construct is used), and this file shows a full source backtrace, allowing for easier debugging. In order to see Vely source code lines, you must use --debug option. You can use --c-lines in order to show the source code lines of the generated C code, instead of Vely code.
  
  
• /var/lib/vv/<app name>/app/db
  Database configuration directory contains the database_config_files used by Vely to connect to databases.
  
  

While Vely directories are fixed, you can effectively change their location by creating a soft link. This way, your directories and files can be elswhere, even on a different disk. For example, to house your files on a different disk:

ln -s /home/disk0/file /var/lib/vv/<app name>/app/file

Memory allocation

Vely uses its own memory allocator when creating internal memory or variables with "define" clause or with any constructs that create new memory. These variables will be automatically freed upon the completion of the request - you can also explicitly free them, but that is not recommended unless absolutely necessary. This approach avoids costly errors, crashes and memory leaks. See memory_handling.

Data types

Vely language_constructs use mostly strings (char* type) and numbers ("num" type, which is "long long" for maximum range of uses), and other data types as specified. If a type is not specified, it is either a string or a number, depending on the context in which it is used - in those cases the type is not specified for simplicity.

General ( quality_control   vely_removal   rename_files   vely   vf   vv   how_vely_works   vely_architecture   vely_SELinux   deploying_application  )  SEE ALL (documentation)