Low Level Functions

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

• callgc()
• varptr()
• space()
• nullpointer()
• object2pointer()
• pointer2object()

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.

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).