globalcontext.h

Include dependency graph for globalcontext.h:

This graph shows which files directly or indirectly include globalcontext.h:

GlobalContext struct and related management functions.

GlobalContext keeps the state of an AtomVM instance, multiple instances can run simultaneously.

Defines

INVALID_PROCESS_ID 0

TYPEDEF_MODULE

Typedefs

typedef struct Module Module

Functions

GlobalContext *globalcontext_new()

Creates a new GlobalContext.

Allocates a new GlobalContext struct and initialize it, the newly created global context is a new AtomVM instance.

Returns:

A newly created GlobalContext.

void globalcontext_destroy(GlobalContext *glb)

Destoys an existing GlobalContext.

Frees global context resources and memory and removes it from the processes table.

Parameters:

• glb – the global context that will be destroyed.

Context *globalcontext_get_process_nolock(GlobalContext *glb, int32_t process_id)

Gets a Context from the process table, without acquiring a lock on the process table.

Retrieves from the process table the context with the given local process id. If the process can be found, without locking the process table. This is unsafe unless a lock on the process table has been obtained previously.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the local process id.

Returns:

a Context * with the requested local process id or NULL if not found.

Context *globalcontext_get_process_lock(GlobalContext *glb, int32_t process_id)

Gets a Context from the process table, acquiring a lock on the process table.

Retrieves from the process table the context with the given local process id. If the process can be found, the process table is locked.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the local process id.

Returns:

a Context * with the requested local process id or NULL if not found.

void globalcontext_get_process_unlock(GlobalContext *glb, Context *c)

Unlock the process table after c was gotten.

Parameters:

• glb – the global context (that owns the process table).

• c – the result of globalcontext_get_process_lock. If NULL, does nothing, otherwise releases the lock on process table.

bool globalcontext_process_exists(GlobalContext *glb, int32_t process_id)

Determine if a process exists.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the local process id.

Returns:

true if a process exists with this id.

void globalcontext_send_message(GlobalContext *glb, int32_t process_id, term t)

Send a message to a process identified by its id.

Safely send a message to the process, doing nothing is the process cannot be found.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the local process id.

• t – the message to send.

void globalcontext_send_message_nolock(GlobalContext *glb, int32_t process_id, term t)

Send a message to a process from another process. There should be a lock on the process table. This variant can be used by listener handlers as an optimization (instead of sending a message to the port context which should then forward it to the target context).

Safely send a message to the process, doing nothing if the process cannot be found.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the target process id.

• t – the message to send.

void globalcontext_send_message_from_task(GlobalContext *glb, int32_t process_id, enum MessageType type, term t)

Send a message to a process identified by its id. This variant is to be used from task drivers. It tries to acquire the necessary locks and if it fails, it enqueues the message which will be delivered on the next scheduler context switch.

Safely send a message to the process, doing nothing if the process cannot be found.

Parameters:

• glb – the global context (that owns the process table).

• process_id – the target process id.

• type – the type of message to send, can be NormalMessage or a signal

• t – the message to send.

void globalcontext_refc_decrement_refcount_from_task(GlobalContext *glb, struct RefcBinary *refc)

Enqueue a refc binary from a task driver, to be refc decremented later from the scheduler.

Parameters:

• glb – the global context

• refc – the refc binary to enqueue

void globalcontext_process_task_driver_queues(GlobalContext *glb)

Process refc binaries and messages enqueued from task drivers.

This function is called from the scheduler.

Parameters:

• glb – the global context

void globalcontext_init_process(GlobalContext *glb, Context *ctx)

Initialize a new process, providing it with a process id.

This function also inserts the process into the process and waiting tables.

Parameters:

• glb – the global context.

• ctx – the process to initialize

bool globalcontext_register_process(GlobalContext *glb, int atom_index, int local_process_id)

Register a process.

Register a process with a certain name (atom) so it can be easily retrieved later.

Parameters:

• glb – the global context, each registered process will be globally available for that context.

• atom_index – the atom table index.

• local_process_id – the process local id.

Returns:

true if the process was registered, false if another process with the same name already existed

int globalcontext_get_registered_process(GlobalContext *glb, int atom_index)

Get a registered process.

Returns the local process id of a previously registered process.

Parameters:

• glb – the global context.

• atom_index – the atom table index.

Returns:

a previously registered process local id.

bool globalcontext_unregister_process(GlobalContext *glb, int atom_index)

Unregister a process by name.

Unregister a process with a certain name (atom).

Parameters:

• glb – the global context, each registered process will be globally available for that context.

• atom_index – the atom table index.

Returns:

true if the process was unregistered, false otherwise

void globalcontext_maybe_unregister_process_id(GlobalContext *glb, int process_id)

Remove entry(ies) from registered atoms by process id.

Unregister a process with a certain process id. This is used when a process dies to ensure the process is not registered and remove it from the registered atoms table if it is.

Parameters:

• glb – the global context, each registered process will be globally available for that context.

• process_id – the process id of the entry to remove.

static inline int globalcontext_insert_atom_maybe_copy(GlobalContext *glb, AtomString atom_string, int copy)

Inserts an atom into the global atoms table, making a copy of the supplied atom string, if copy is non-zero.

Inserts an atom into the global atoms table and returns its id.

Parameters:

• glb – the global context.

• atom_string – the atom string that will be added to the global atoms table, it will not be copied so it must stay allocated and valid.

• copy – if non-zero, make a copy of the input atom_string if the atom is not already in the table. The table assumes “ownership” of the allocated memory.

Returns:

newly added atom id or -1 in case of failure.

static inline int globalcontext_insert_atom(GlobalContext *glb, AtomString atom_string)

equivalent to globalcontext_insert_atom_maybe_copy(glb, atom_string, 0);

bool globalcontext_is_atom_index_equal_to_atom_string(GlobalContext *glb, int atom_index_a, AtomString atom_string_b)

Compares an atom table index with an AtomString.

Checks if the given atom table index and the given AtomString refers to the same atom.

Parameters:

• glb – the global context.

• atom_index_a – an atom table index.

• atom_string_b – an atom string, which is the atom length followed by atom characters.

Returns:

true if they both refer to the same atom, otherwise false.

static inline bool globalcontext_is_term_equal_to_atom_string(GlobalContext *global, term atom_a, AtomString atom_string_b)

Compares a term with an AtomString.

Checks if the given term and the given AtomString refers to the same atom.

Parameters:

• global – the global context.

• atom_a – any term of any type, when it is not an atom false is always returned.

• atom_string_b – an atom string, which is the atom length followed by atom characters.

Returns:

true if they both refer to the same atom, otherwise false.

static inline term globalcontext_make_atom(GlobalContext *glb, AtomString string)

Returns a term representing an atom, from the suppliend string.

Converts a string to an atom. Note that this function may have a side-effect on the global context.

Parameters:

• glb – pointer to the global context

• string – an AtomString

Returns:

an atom term formed from the supplied atom string.

AtomString globalcontext_atomstring_from_term(GlobalContext *glb, term t)

Returns the AtomString value of a term.

This function fetches the AtomString value of the atom associated with the supplied term. The input term must be an atom type. If no such atom is registered in the global table, this function returns NULL. The caller should NOT free the data associated with the returned value.

Parameters:

• glb – the global context

• t – the atom term

Returns:

the AtomString associated with the supplied atom term.

term globalcontext_existing_term_from_atom_string(GlobalContext *glb, AtomString atom_string)

Returns the term for an existing atom.

This function allows to get an atom term associated to the given atom string, if and only if the given atom is already in the atom table, otherwise an invalid term is returned.

Parameters:

• glb – the global context.

• atom_string – the atom string that will be looked into the atom table.

Returns:

the term associated with the supplied atom string when already existing in the atom table, otherwise an invalid term.

int globalcontext_insert_module(GlobalContext *global, Module *module)

Inserts a module to the modules table.

Inserts an already loaded module to the modules table and assigns and index to it so it can be retrieved later by name or index. The module is then owned by the global context that will destroy it when globalcontext_destroy is invoked.

Parameters:

• global – the global context.

• module – the module that will be added to the modules table.

Returns:

the module index if successful, otherwise -1.

Module *globalcontext_get_module_by_index(GlobalContext *global, int index)

Get a module by index.

Safely retrieve the module by index considering the table can be reallocated by globalcontext_insert_module.

Parameters:

• global – the global context.

• index – the module index.

Returns:

the module

Module *globalcontext_get_module(GlobalContext *global, AtomString module_name_atom)

Returns the module with the given name.

Tries to get the module with the given name from the modules table and eventually loads it.

Parameters:

• global – the global context.

• module_name_atom – the module name.

Returns:

a pointer to a Module struct.

Module *globalcontext_load_module_from_avm(GlobalContext *global, const char *module_name)

Load a given module from registered AVM packs.

This function is typically called from sys_load_module. It does not check if the module is already loaded and allocates a new module structure.

Parameters:

• global – the global context.

• module_name_atom – the module name.

Returns:

a pointer to a Module struct or NULL if the module could not be found.

bool globalcontext_demonitor(GlobalContext *global, uint64_t ref_ticks)

remove a monitor

iterate on the list of all processes and then on each monitor to find a given monitor, and remove it

Parameters:

• global – the global context

• ref_ticks – the reference to the monitor

Returns:

true if the monitor was found

static inline uint64_t globalcontext_get_ref_ticks(GlobalContext *global)

struct MessageQueueItem

#include <globalcontext.h>

Collaboration diagram for MessageQueueItem:

Public Members

struct MessageQueueItem *next

MailboxMessage *message

int32_t process_id

struct RefcBinaryQueueItem

#include <globalcontext.h>

Collaboration diagram for RefcBinaryQueueItem:

Public Members

struct RefcBinaryQueueItem *next

struct RefcBinary *refc

struct GlobalContext

#include <globalcontext.h>

Collaboration diagram for GlobalContext:

Public Members

struct ListHead ready_processes

struct ListHead running_processes

struct ListHead waiting_processes

SpinLock processes_spinlock

struct MessageQueueItem *message_queue

struct RefcBinaryQueueItem *refc_queue

struct SyncList refc_binaries

struct SyncList processes_table

struct SyncList registered_processes

struct SyncList listeners

struct SyncList resource_types

struct SyncList select_events

struct Ets ets

int32_t last_process_id

struct AtomTable *atom_table

struct AtomsHashTable *modules_table

RWLock *modules_lock

Module **modules_by_index

int loaded_modules_count

struct SyncList avmpack_data

struct TimerList timer_list

SpinLock timer_spinlock

unsigned long long ref_ticks

SpinLock ref_ticks_spinlock

int online_schedulers

int running_schedulers

bool waiting_scheduler

Mutex *schedulers_mutex

CondVar *schedulers_cv

bool scheduler_stop_all

SpinLock env_spinlock

void *platform_data