NAME

gc_clients_init - initialize the GC library. Invoke before any network activity.

SYNOPSIS

#include <game-carrier/client.h>

GC_CLIENT_API
GCT_INT gc_clients_init(
    GCT_INT mode);

Parameters:

• mode GCT_INT Identifies the initialization mode of the function.

RETURN VALUE

Returns 0 if the operation is successful.

Standard error codes like EINVAL or ENOMEM are returned if initialization fails.

DESCRIPTION

The gc_clients_init function initializes the Game Carrier client library and it must be invoked before performing any network operations such as: establishing connections, sending messages and other.

When the client library is no longer needed, use the gc_clients_cleanup function to stop all network operations and free the allocated resources.

The mode parameter identifies the initialization mode of the function. Suported values: GC_MODE_ACTIVE (2), GC_MODE_PASSIVE (1), GC_MODE_HYBRID (3).

GC_MODE_ACTIVE (2)

When the Active mode is used, a new thread is created and it is used for all network activity. All events are called in that thread right after they occur. All outgoing network messages are sent immediately. When using this mode, you have to implement the thread synchronization.

GC_MODE_PASSIVE (1)

When the Passive mode is used, no additional threads are created. All network activity occurs in the same thread where the gc_clients_service is called, and it also applies to all events. All outgoing messages are processed only after the gc_clients_service function is invoked.

GC_MODE_HYBRID (3)

When the Hybrid mode is used, a new thread is created and it is used for all network activity. All events are put into an internal queue and delivered to a game only when the gc_clients_service is invoked in the same thread. All outgoing network messages are sent immediately.

Recommendations

We strongly recommend using the Hybrid mode by default, since it combines the advantages of the Active and Passive modes, namely: All network activity is processed in a separate thread, which results in better performance. And all network messages are delivered to the user threads, making thread communication simple.

It is recommended to use the Passive mode for single-threaded games that have low resource requirements.

The Active mode is recommended for developing high-performance games. Thread synchronization is strongly advised when using this mode.

The summary of all modes can be found in the table below:

EXAMPLE

#include <game-carrier/client.h>

#include <stdio.h>

int mode = GC_MODE_HYBRID;
int finished = 0;

int main(int argc, char * argv[])
{
    /* Client library initialization */
    int ret = gc_clients_init(mode);
    if (ret != 0) {
        fprintf(stderr, "Failed to initialize the Game Carrier client library\n");
        return 1;
    }

    /* Game loop */
    while (!finished) {

        /* Perform related game activity, like drawing a new frame */
        draw_new_frame();

        /* Handling network */
        if (mode == GC_MODE_PASSIVE || mode == GC_MODE_HYBRID) {
            gc_clients_service();
        }
    }

    /* Client library finalization */
    gc_clients_cleanup();
    return 0;
}

SEE ALSO

gc_clients_service, gc_clients_cleanup