Low Level Functions¶

In this chapter we will learn about the low level functions provided by Ring

callgc()
varptr()
space()
nullpointer()
object2pointer()
pointer2object()
ptrcmp()
ringvm_cfunctionslist()
ringvm_functionslist()
ringvm_classeslist()
ringvm_packageslist()
ringvm_memorylist()
ringvm_calllist()
ringvm_fileslist()

callgc() function¶

Use this function to force calling the garbage collector during function execution when you use a loop that create temp. variables that you don’t free using the assignment operation.

It’s very rare to need this function but it’s useful when you create something like event-loop for your game engine and start creating lists on the fly when you call functions.

Example

While True

        # process events
        # call functions using temp. lists like myfunc(["temp list"])

        # call the garbage collector
        callgc()
End

Tip

In Ring the garbage collector works automatically in the end of function execution or when you use the assignment statement.

varptr() function¶

Use the varptr() function when you need to pass a pointer to a C/C++ function.

Syntax:

varptr(cVariableName,cPointerType) —> Low Level Object (C Pointer)

example:

r = 10
z = 20
see r + nl
see varptr("r","int")
see varptr("z","int")

Output:

10
00E3C740
int
2
00E3BEC0
int
2

Note

the low level object is a list contains three items (The Pointer, The Type, The Status)

space() function¶

Use the space function to allocate a specific number of bytes in Memory.

Syntax:

Space(nBytesCount) ---> String

Example:

mystring = space(200)
See "String Size : " + len(mystring) + nl
See "String : " + mystring + nl
See "String Pointer : "
See varptr("mystring","char *")

Output:

String Size : 200
String :
String Pointer : 00FF8FE8
char *
2

Note

You may need the space() and VarPtr() functions to pass buffers to C functions.

nullpointer() function¶

You may need to pass the NULL pointer to a C function that may expect a pointer as parameter and accept NULL pointers for optional parameters.

Example:

The next example uses the SDL_BlitSurface() function from the LibSDL Library through RingSDL The function accept SDL_Rect pointers in the second and the last parameter. Also the function accept NULL pointers, so we can pass them using the NULLPointer() Function.

SDL_BlitSurface(text, nullpointer(), surface, nullpointer())

Note

The previous code doesn’t work alone, you need to learn how to use RingSDL first.

Tip

We can pass NULL as parameter instead of using NULLPointer()

object2pointer() function¶

Use this function to get a C pointer for Ring lists and objects

Syntax:

object2pointer(List|Object) --> Low Level Object ( C Pointer )

pointer2object() function¶

Use this function to get the Ring list and/or object from the low level object (C Pointer)

Syntax:

pointer2object(Low Level Object) ---> List|Object

Example:

# Create the list
mylist = 1:5

# Create pointer to the list
x = object2pointer(mylist)
see x

see nl

# Add items to the list
mylist + "welcome"

# print the list items
y = pointer2object(x)
see y

Output:

0069A5D8
OBJECTPOINTER
0

1
2
3
4
5
welcome

Note

In Ring the assignment operator copy lists and objects by value, to copy by reference Just use the object2pointer() and pointer2object() functions.

Tip

The object2pointer() and pointer2object() are used in the stdlib - Tree Class implementation to create a reference for the parent node (object) in the child node (another object).

ptrcmp() function¶

We can compare between two pointers (C Objects) using the ptrcmp() function.

Syntax:

ptrcmp(oObject1,oObject2) ---> value = 1 if oObject1 = oObject2
                               value = 0 if oObject1 != oObject2

Example:

fp = fopen("ptrcmp.ring","r")
fp2 = fp
fp3 = fopen("ptrcmp.ring","r")

see ptrcmp(fp,fp2) + nl
see ptrcmp(fp,fp3) + nl

fclose(fp)
fclose(fp3)

Output:

1
0

ringvm_cfunctionslist() function¶

The Function return a list of functions written in C.

Syntax:

RingVM_CFunctionsList() ---> List

Example:

See RingVM_CFunctionsList()

ringvm_functionslist() function¶

The Function return a list of functions written in Ring.

Each List Member is a list contains the next items

Function Name
Program Counter (PC) - Function Position in Byte Code.
Source Code File Name
Private Flag (For Private Methods in Classes)

Syntax:

RingVM_FunctionsList() ---> List

Example:

test()

func test
        see ringvm_functionslist()

Output:

test
8
B:/ring/tests/scripts/functionslist.ring
0

ringvm_classeslist() function¶

The Function return a list of Classes.

Each List Member is a list contains the next items

Class Name
Program Counter (PC) - Class Position in Byte Code.
Parent Class Name
Methods List
Flag (Is parent class information collected)
Pointer to the package (or NULL if no package is used)

Syntax:

RingVM_ClassesList() ---> List

Example:

see ringvm_classeslist()

class class1
        func f1
class class2 from class1
class class3 from class1

Output:

class1
9

f1
13
B:/ring/tests/scripts/classeslist.ring
0
0
00000000
class2
16
class1
0
00000000
class3
20
class1
0
00000000

ringvm_packageslist() function¶

The Function return a list of Packages.

Each List Member is a list contains the next items

Package Name
Classes List

Syntax:

RingVM_PackagesList() ---> List

Example:

see ringvm_packageslist()

package package1
        class class1

package package2
        class class1

package package3
        class class1

Output:

package1
class1
11

0
00FEF838
package2
class1
17

0
00FEF978
package3
class1
23

0
00FEFF68

ringvm_memorylist() function¶

The Function return a list of Memory Scopes and Variables.

Each List Member is a list contains variables in a different scope.

Each Item in the scope list is a list contains the next items

Variable Name
Variable Type
Variable Value
Pointer Type (List/Item) if the value is a list
Private Flag (if the variable is an attribute in a Class)

Syntax:

RingVM_MemoryList() ---> List

Example:

x = 10
test()
func test
        y = 20
        see ringvm_memorylist()

Output:

true
2
1
0
0
false
2
0
0
0
nl
1


0
0
null
1

0
0
ring_gettemp_var
4
00000000
0
0
ccatcherror
1
NULL
0
0
ring_settemp_var
4
00000000
0
0
ring_tempflag_var
2
0
0
0
stdin
3
50512DB8
file
0
0
0
stdout
3
50512DD8
file
0
0
0
stderr
3
50512DF8
file
0
0
0
this
4
00000000
0
0
sysargv
3
B:\ring\bin/ring
B:/ring/tests/scripts/memorylist.ring
0
0
x
2
10
0
0
y
2
20
0
0

ringvm_calllist() function¶

The Function return a list of the functions call list.

Each List Member is a list contains the next items

Function Type
Function Name
Program Counter (PC)
Stack Pointer (SP)
Temp. Memory List
Method or Function Flag
Caller PC
FuncExec Flag
ListStart Flag
Nested Lists Pointer
State List

Syntax:

RingVM_CallList() ---> List

Example:

hello()
func hello
        test()

func test
        mylist = ringvm_calllist()
        for t in mylist see t[2] + nl next

Output:

function hello() in file B:/ring/tests/scripts/calllist.ring
called from line 1
function test() in file B:/ring/tests/scripts/calllist.ring
called from line 3
ringvm_calllist

ringvm_fileslist() function¶

Function return a list of the Ring Files.

Syntax:

RingVM_FilesList() ---> List

Example:

load "stdlib.ring"
see ringvm_fileslist()

Output:

B:/ring/tests/scripts/fileslist.ring
B:\ring\bin\stdlib.ring
eval
stdlib.ring
stdlib.rh
stdclasses.ring
stdfunctions.ring
stdbase.ring
stdstring.ring
stdlist.ring
stdstack.ring
stdqueue.ring
stdmath.ring
stddatetime.ring
stdfile.ring
stdsystem.ring
stddebug.ring
stddatatype.ring
stdconversion.ring
stdodbc.ring
stdmysql.ring
stdsecurity.ring
stdinternet.ring
stdhashtable.ring
stdtree.ring

Low Level Functions¶

callgc() function¶

varptr() function¶

space() function¶

nullpointer() function¶

object2pointer() function¶

pointer2object() function¶

ptrcmp() function¶

ringvm_cfunctionslist() function¶

ringvm_functionslist() function¶

ringvm_classeslist() function¶

ringvm_packageslist() function¶

ringvm_memorylist() function¶

ringvm_calllist() function¶

ringvm_fileslist() function¶

Table Of Contents

Previous topic

Next topic

This Page