---
name: "cpg_model_initialize"
section: "3"
platform: "linux"
package: "libcpg-dev"
version: "3.1.9-2+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cpg_model_initialize"
---

# cpg\_model\_initialize(3)

Create a new connection to the CPG service

## NAME

cpg\_model\_initialize - Create a new connection to the CPG service

## SYNOPSIS

**#include \<corosync/cpg.h\>**

**cs\_error\_t cpg\_model\_initialize(cpg\_handle\_t \****handle***, cpg\_model\_t** *model***, cpg\_model\_data\_t \****model\_data***, void \****context***);**

## DESCRIPTION

The **cpg\_model\_initialize** function is used to initialize a connection to the closed process groups API.

Each application may have several connections to the CPG API.  Each application uses the *handle* argument to uniquely identify the connection.  The *handle* argument is then used in other function calls to identify the connection to be used for communication with the CPG service.

Argument *model* is used to explicitly choose set of callbacks and internal parameters. Currently only model *CPG\_MODEL\_V1* is defined.

Callbacks and internal parameters are passed by *model\_data* argument. This is casted pointer (idea is similar as in sockaddr function) to one of structures corresponding to chosen model. Currently only *cpg\_model\_v1\_data\_t* is needed.

## MODEL\_V1

The *MODEL\_V1* is backwards compatible with original callbacks initialized by *cpg\_initialize* but new callback *cpg\_totem\_confchg\_fn* is defined.

Every time an CPG event occurs within the joined group, one of the callbacks specified by the argument *callbacks* is called.  The callback functions are described by the following type definitions:

-

  ```
  typedef void (*cpg_deliver_fn_t) (
          cpg_handle_t handle,
          const struct cpg_name *group_name,
          uint32_t nodeid,
          uint32_t pid,
          const void *msg,
          size_t msg_len);
  typedef void (*cpg_confchg_fn_t) (
          cpg_handle_t handle,
          const struct cpg_name *group_name,
          const struct cpg_address *member_list, size_t member_list_entries,
          const struct cpg_address *left_list, size_t left_list_entries,
          const struct cpg_address *joined_list, size_t joined_list_entries);
  typedef void (*cpg_totem_confchg_fn_t) (
          cpg_handle_t handle,
          struct cpg_ring_id ring_id,
          uint32_t member_list_entries,
          const uint32_t *member_list);
  ```

-

  The *cpg\_model\_v1\_data\_t* structure is defined as:

-

  ```

  ```

  typedef struct {\
           cpg\_model\_t model;\
           cpg\_deliver\_fn\_t cpg\_deliver\_fn;\
           cpg\_confchg\_fn\_t cpg\_confchg\_fn;\
           cpg\_totem\_confchg\_fn\_t cpg\_totem\_confchg\_fn;\
           unsigned int flags; } cpg\_model\_v1\_data\_t;

-

  When a configuration change occurs or a message is to be delivered one of the callbacks is called from the **cpg\_dispatch()** function.  If a configuration change occurs, *cpg\_confchg\_fn* is called.  If a delivery of a message occurs, *cpg\_deliver\_fn* is called. When totem membership change occurs, *cpg\_totem\_confchg\_fn* is called. You can OR *CPG\_MODEL\_V1\_DELIVER\_INITIAL\_TOTEM\_CONF* constant to flags to get callback after first confchg event.

The *cpg\_address* structure is defined

-

  ```

  ```

  struct cpg\_address {\
           unsigned int nodeid;\
           unsigned int pid;\
           unsigned int reason; };

-

  where nodeid is a 32 bit unique node identifier, pid is the process ID of the process that has joined/left the group or sent the message, and reason is an integer code indicating why the node joined/left the group (this value is not set for the member\_list items).

-

  ```

  ```

  CPG\_REASON\_JOIN      - the process joined a group using cpg\_join(). CPG\_REASON\_LEAVE     - the process left a group using cpg\_leave() CPG\_REASON\_NODEDOWN  - the process left a group because the node left the cluster. CPG\_REASON\_NODEUP    - the process joined a group because it was already a member of a group on a node that has just joined the cluster CPG\_REASON\_PROCDOWN  - the process left a group without calling cpg\_leave() CPG\_REASON\_UNDEFINED - a special value used for the member\_list items

-

  The *cpg\_ring\_id* structure is defined

-

  ```

  ```

  struct cpg\_ring\_id {\
           uint32\_t nodeid;\
           uint64\_t seq; };

-

  where *nodeid* is the current Totem leader and *seq* is an increasing number.

## RETURN VALUE

This call returns the CS\_OK value if successful, otherwise an error is returned.

## ERRORS

The errors are undocumented.

## SEE ALSO

[**cpg\_overview**(3)](/cpg_overview/3.md), [**cpg\_initialize**(3)](/cpg_initialize/3.md), [**cpg\_finalize**(3)](/cpg_finalize/3.md), [**cpg\_fd\_get**(3)](/cpg_fd_get/3.md), [**cpg\_dispatch**(3)](/cpg_dispatch/3.md), [**cpg\_join**(3)](/cpg_join/3.md), [**cpg\_leave**(3)](/cpg_leave/3.md), [**cpg\_mcast\_joined**(3)](/cpg_mcast_joined/3.md), [**cpg\_membership\_get**(3)](/cpg_membership_get/3.md) [**cpg\_zcb\_alloc**(3)](/cpg_zcb_alloc/3.md) [**cpg\_zcb\_free**(3)](/cpg_zcb_free/3.md) [**cpg\_zcb\_mcast\_joined**(3)](/cpg_zcb_mcast_joined/3.md) [**cpg\_context\_get**(3)](/cpg_context_get/3.md) [**cpg\_context\_set**(3)](/cpg_context_set/3.md) [**cpg\_local\_get**(3)](/cpg_local_get/3.md) [**cpg\_model\_initialize**(3)](/cpg_model_initialize/3.md)

**CS\_ERR\_TRY\_AGAIN** Resource temporarily unavailable

**CS\_ERR\_INVALID\_PARAM** Invalid argument

**CS\_ERR\_ACCESS** Permission denied

**CS\_ERR\_LIBRARY** The connection failed

**CS\_ERR\_INTERRUPT** System call interrupted by a signal

**CS\_ERR\_NOT\_SUPPORTED** The requested protocol/functionality not supported

**CS\_ERR\_MESSAGE\_ERROR** Incorrect auth message received

**CS\_ERR\_NO\_MEMORY** Not enough memory to complete the requested task