docs/en/source/generalinfo.txt

   1 .. index::
   2         single: General Information; Introduction
   3
   4 ===================
   5 General Information
   6 ===================
   7
   8 This chapter contains general information about the Ring programming language
   9
  10 (1) Ring Architecture
  11 (2) Memory Management
  12 (3) Data Representation
  13
  14 .. index::
  15         pair: General Information; Ring Architecture
  16
  17 Ring Architecture
  18 =================
  19
  20 We have the next architecture
  21
  22 (1) Ring Applications (Your Code)  - Written in Ring - See folder : ring/applications
  23 (2) Ring Libraries (StdLib, WebLib, GameEngine, etc) - Written in Ring - See folder : ring/ringlibs
  24 (3) Ring Extensions (RingAllegro, RingQt, etc) - Written in C/C++ (may include Ring code) - See folder : ring/extensions
  25 (4) Ring Virtual Machine (Ring VM) - Written in C language
  26 (5) Operating System (Current Platform) - (Windows, Linux, macOS, Android, etc)
  27
  28 The extensions are just dynamic libraries (DLL, So, Dylib)
  29 You can update the extensions without the need to update your code.
  30
  31
  32 Folder (ring\libdepwin) ====> C libraries used for building Ring Extensions (written in C) on Windows platform.
  33
  34 Folder (ring\ringlibs)  ====> Ring libraries written in Ring itself (StdLib, WebLib, GameEngine, etc)
  35
  36 Folder (ring\rnoteexe)  ====> Just C source file to create executable file that will run rnote.ring
  37
  38 Folder (ring\visualsrc) ====> The Visual Source Code of the Ring Compiler & Ring VM developed using Programming Without Coding Technology (PWCT)
  39
  40 We use the term Ring Library ---> When the library code is written in Ring
  41 We use the term Ring Extension ---> When the library code is Written in C or C++
  42
  43 .. index::
  44         pair: General Information; Memory Management
  45
  46 Memory Management
  47 =================
  48
  49 (1) When we call function, we get a new scope for this function, inside this scope we store variables.
  50
  51 Also we get Temp. memory for this function. Inside this temp. memory we store temp. lists
  52
  53 All of this will be deleted directly after the end of the function call (end of scope)
  54
  55 (2) In Ring to delete memory, you have the next options
  56
  57 2.1 Wait until the end of the function scope
  58
  59 2.2 Use the Assignment operator
  60
  61 2.3 Use callgc() function (delete temp. lists only)
  62
  63 (3) Ring Garbage Collector uses Escape Analysis and Reference Counting
  64
  65 In 90% of cases, the Escape Analysis is used so we don't waste time in running the garbage collector
  66 We directly know what will be deleted and what will remain in the memory.
  67
  68 https://en.wikipedia.org/wiki/Escape_analysis
  69
  70 In 10% of cases (or less than that) Ring may use Reference Counting.
  71
  72 For example when we pass a list and sub list to a function
  73 Ring will pass the lists by reference, but what will happens if we deleted the Parent List?
  74 In this case, the Sub List will use reference counting, and when deleting the Parent List, it will stay in memory until the end of the function.
  75
  76 Remember that Ring encourage us to avoid using references, and the
  77 Assignment Operator will copy lists by value, so Ring usage of reference counting is
  78 very limited to special cases and in most cases the Escape Analysis is enough which is very fast.
  79
  80 Starting from Ring 1.9 we extended the Reference Counting support to Ring Extensions and low level C pointers.
  81 So we don't have to care about using fclose() when we use fopen() for example. and the same for
  82 other extensions like RingODBC, RingSQLite, RingMySQL, RingQt, etc.
  83
  84 All of the allocated resources will be cleaned by the Garbage Collector when we finish using it (when we lost the last reference).
  85
  86
  87 .. index::
  88         pair: General Information; Data Representation
  89
  90 Data Representation
  91 ===================
  92
  93 (1) In Ring, The String is just (Array of bytes)
  94
  95 Ring is 8-bit clean, Each character in the string is 8 bits (1 byte)
  96
  97 So these functions (Int2Bytes(), Float2Bytes() and Double2Bytes()) just return a string.
  98
  99 Also we can store binary data in strings
 100
 101 .. code-block:: ring
 102
 103         mystring = read("myfile.exe")
 104
 105 (2) Remember this, when you think about variables
 106
 107 * Value ---> What we have (What we are storing in the computer memory as data) - Low Level Concept
 108 * Type  ---> What we can do with what we have or how we do things with what we have (Just a Logical Concept)
 109
 110 Computer memory ----> Just store [Bytes] - Each byte is 8-bit - (Here we avoid the memory word concept)
 111
 112 These bytes could be grouped together when moved between the memory and the processor registers.
 113 Here we have (The register size) and things like 32-bit and 64-bit for example.
 114 Also we have the bytes order.
 115
 116 Programming Languages ----> Add Types (Just as a concept) to these bytes so we can determine what to do with them and how operations should be done.
 117
 118 And programming language could allow (Type Conversion) ---> Because the Type is a logical concept in most cases, What we really have is just data (Bytes, Bytes Count, Bytes Order, etc)
 119
 120 Ring Stings ----> You have these bytes (each byte is 8-bit) and Ring know the string size (stored as number in the String structure)
 121
 122 So we don't check the NULL character or add it to the end of the string (Not Required)
 123
 124 All operations inside Ring VM, will check the Ring size and deal with the string as binary data (each character is 8-bit)
 125
 126 In the C language ---> The normal case is adding NULL character (\0) to the end of each string
 127
 128 And the string functions check this character, This is not suitable for binary data.
 129
 130 Signed vs Unsigned ---> Is a logical concept which is important when you do arithmetic operations on the data, but when storing the data, if you will include all of the (8-bits) and will not ignore any of them ---> Then don't care.
 131
 132 In Ring, don't think about these details, we are hiding it from you, so you can focus on your application and what you will do.
 133
 134 Think in C when you write C code which could be (based on need) low level code to have control on everything.
 135  ----> Good for performance and memory management
 136
 137 Think in Ring when you write Ring code which let you ignore a lot of details and concentrate only on the result
 138 -----> Good for productivity and delivering software quickly
 139
 140 The good news (We can mix between Ring and C in our projects)
 141
 142
 143 (3) The functions Int2Bytes(), Float2Bytes() and Double2Bytes()
 144
 145 These function take input as (Number) ---> Convert it to group of bytes based on the number type (int|float|double) ---> Then return a Ring string that contains these bytes
 146
 147 Int2Bytes() ---> Ring string (Group of bytes) and the string size = sizeof(int)
 148
 149 Float2Bytes() ---> Ring string (Group of bytes) and the string size = sizeof(float)
 150
 151 Double2Bytes() ---> Ring string (Group of bytes) and the string size = sizeof(double)
 152
 153 Example:
 154
 155 .. code-block:: ring
 156
 157         ? len( int2bytes(1) )
 158         ? len( float2bytes(1) )
 159         ? len( double2bytes(1) )
 160
 161 Output:
 162
 163 .. code-block:: none
 164
 165         4
 166         4
 167         8
 168
 169 (4) Storing Numbers
 170
 171 When we use a number, Ring always use the (Double) data type for representing these numbers in memory.
 172 This is important to know when we do arithmetic operations on numbers.
 173
 174 But when we convert the number to a String using "" + number  or using string(number) we get a string where each digit is represented in 1 byte (Not good idea for storage, but useful for string processing)
 175
 176 If you need the number to be represented in specific size (int|float|double) for storage then use bytes2int() , bytes2float() and bytes2double() when writing the data to binary files.
 177
 178 Ring Number (double) ----> int2bytes()  - will cast the number from double to int then return the bytes ----> 4 bytes (Ring String)
 179
 180 Ring Number (double) ----> float2bytes()  - will cast the number from double to float then return the bytes ----> 4 bytes (Ring String)
 181
 182 Ring Number (double) ----> double2bytes()  - will use the number (double) to return the bytes ----> 8 bytes (Ring String)
 183
 184 The (int) type is used only for internal Ring operations, but Ring applications|code will use only the (double) type for numbers.
 185
 186 (5) The Unsigned() Function
 187
 188 The function unsigned() expect the first and the second parameters as numbers
 189
 190 .. code-block:: ring
 191
 192         unsigned(nNumber1,nNumber2,cOperator)
 193
 194 We can use the bytes2int() function to convert the bytes to a number
 195
 196 Example:
 197
 198 .. code-block:: ring
 199
 200         B = list(4)
 201
 202         for k=1 to 4
 203         {
 204                 B[k]= Space(4)
 205                 for kk=1 to 4 { B[k][kk]= char(60+4*k +kk) }
 206                 ? " B" +k +": " +B[k]
 207         }
 208
 209         A12= Space(4)     A12= bytes2int(B[1]) ^ bytes2int(B[2])
 210         ? "A12: " +string(A12)
 211         A34= Space(4)     A34= bytes2int(B[3]) ^ bytes2int(B[4])
 212         ? "A34: " +string(A34)
 213         A12= space(4)     A12= Unsigned(bytes2int(B[1]),bytes2int(B[2]),"^")
 214         ? "unsigned A12: " +A12
 215         A34= space(4)     A34= Unsigned(bytes2int(B[3]),bytes2int(B[4]),"^")
 216         ? "unsigned A34: " +A34
 217
 218 Output:
 219
 220 .. code-block:: none
 221
 222         B1: ABCD
 223         B2: EFGH
 224         B3: IJKL
 225         B4: MNOP
 226         A12: 201589764
 227         A34: 470025220
 228         unsigned A12: 201589764
 229         unsigned A34: 470025220