{"id":15646292,"url":"https://github.com/izeigerman/pittacus","last_synced_at":"2025-04-30T12:07:31.548Z","repository":{"id":210934001,"uuid":"77468248","full_name":"izeigerman/pittacus","owner":"izeigerman","description":"Gossip protocol implementation in C","archived":false,"fork":false,"pushed_at":"2017-02-01T22:55:39.000Z","size":92,"stargazers_count":58,"open_issues_count":2,"forks_count":19,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-02-25T07:41:47.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/izeigerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-12-27T16:24:56.000Z","updated_at":"2024-12-22T14:01:23.000Z","dependencies_parsed_at":"2023-12-05T17:04:08.539Z","dependency_job_id":null,"html_url":"https://github.com/izeigerman/pittacus","commit_stats":null,"previous_names":["izeigerman/pittacus"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izeigerman%2Fpittacus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izeigerman%2Fpittacus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izeigerman%2Fpittacus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/izeigerman%2Fpittacus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/izeigerman","download_url":"https://codeload.github.com/izeigerman/pittacus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242650896,"owners_count":20163610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T12:12:19.220Z","updated_at":"2025-03-09T05:30:29.560Z","avatar_url":"https://github.com/izeigerman.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# Pittacus\n\n## Description\nPittacus - is an extremely small gossip protocol implementation in pure C. Its main goal is a data dissemination rather than membership management.\nThe crucial features and advantages of Pittacus are the following:\n* Allows to build a fully decentralized P2P cluster without a single server instance.\n* Pittacus is a very lightweight library with zero external dependencies.\n* Utilizes UDP for the transport layer.\n* Very tiny and adjustable memory footprint.\n* Small protocol overhead.\n* The data spreading is pretty fast (subjective statement, didn't have a chance to compare it to other options).\n* It's distributed under the Apache License 2.0.\n\nDon't expect from Pittacus the following:\n* Cluster membership tracking and management. As mentioned above Pittacus - is a dissemination protocol. This means that each node has to be aware only of a small part of the cluster to function properly. While Pittacus is pretty good in fast distribution of data across the cluster, it doesn't provide any guarantees about cluster convergence or data consistency (at least for now).\n* Transferring of huge amounts of data. Since UDP is not a reliable protocol, it imposes some restrictions on a maximum size of each packet (the larger size is - the higher risk to lose a packet). The default maximum message size for Pittacus is 512 bytes (the value is configurable). This includes the protocol overhead, which is only 26 bytes for the data message. So by default the payload size shouldn't exceed 512 - 26 = 486 bytes per one message. This should be enough for a small command or notification together with PKCS#1 signature to verify an initiator.\n\nSo far neither the message delivery order nor the delivery itself have strong guarantees.\n\nNOTE: at this point Pittacus is in active development stage. It can be used for experiments but not for production solutions. A lot of things have to be done in order to release the first version.\n\n## How to build\nInstall CMake \u003e= 3.0.\n```\ngit clone https://github.com/izeigerman/pittacus.git\ncd pittacus\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\n```\n\nTo install Pittacus:\n```\nmake install\n```\n\n## How to use\nFirst of all include the Pittacus header:\n```cpp\n#include \u003cpittacus/gossip.h\u003e\n```\n\nNow instantiate a Pittacus descriptor with a `sockaddr` structure that represents an address of the current node and a data receiver callback:\n```cpp\nstruct sockaddr_in self_in;\nself_in.sin_family = AF_INET;\nself_in.sin_port = htons(65000); // use 0 instead to pick up a random port\ninet_aton(\"127.0.0.1\", \u0026self_in.sin_addr);\n\n// Filling in the address of the current node.\npittacus_addr_t self_addr = {\n    .addr = (const pt_sockaddr *) \u0026self_in,\n    .addr_len = sizeof(struct sockaddr_in)\n};\n\n// Create a new Pittacus descriptor instance.\npittacus_gossip_t *gossip = pittacus_gossip_create(\u0026self_addr, \u0026data_receiver, NULL);\nif (gossip == NULL) {\n    fprintf(stderr, \"Gossip initialization failed: %s\\n\", strerror(errno));\n    return -1;\n}\n```\n\nThe data receiver callback may look like following:\n```cpp\nvoid data_receiver(void *context, pittacus_gossip_t *gossip, const uint8_t *data, size_t data_size) {\n    // This function is invoked every time when a new data arrives.\n    printf(\"Data size is: %u\\n\", data_size);\n}\n```\n\nIt's time join a cluster. There are 2 ways to do this: 1) specify the list of seed nodes that are used as entry points to a cluster or 2) specify nothing if this instance is going to be a seed node in itself.\n```cpp\n// Provide a seed node destination address.\nstruct sockaddr_in seed_node_in;\nseed_node_in.sin_family = AF_INET;\nseed_node_in.sin_port = htons(65000);\ninet_aton(\"127.0.0.1\", \u0026seed_node_in.sin_addr);\n\npittacus_addr_t seed_node_addr = {\n    .addr = (const pt_sockaddr *) \u0026seed_node_in,\n    .addr_len = sizeof(struct sockaddr_in)\n};\n\n// Join a cluster.\nint join_result = pittacus_gossip_join(gossip, \u0026seed_node_addr, 1);\nif (join_result \u003c 0) {\n    fprintf(stderr, \"Gossip join failed: %d\\n\", join_result);\n    pittacus_gossip_destroy(gossip);\n    return -1;\n}\n```\n\nTo force Pittacus to read a message from the network:\n```cpp\nrecv_result = pittacus_gossip_process_receive(gossip);\nif (recv_result \u003c 0) {\n    fprintf(stderr, \"Gossip receive failed: %d\\n\", recv_result);\n    pittacus_gossip_destroy(gossip);\n    return -1;\n}\n```\n\nTo flush the outbound messages to the network:\n```cpp\nsend_result = pittacus_gossip_process_send(gossip);\nif (send_result \u003c 0) {\n    fprintf(stderr, \"Gossip send failed: %d\\n\", recv_result);\n    pittacus_gossip_destroy(gossip);\n    return -1;\n}\n```\n\nIn order to enable the anti-entropy in Pittacus you should periodically call the gossip tick function:\n```cpp\nint time_till_next_tick = pittacus_gossip_tick(gossip);\n```\nThis function returns a time period in milliseconds which indicates when the next tick should occur. This time interval can be used to adjust yor `poll` or `select` timeout. Check out the code documentation for further details.\n\nTo spread some data within a cluster:\n```cpp\npittacus_gossip_send_data(gossip, data, data_size);\n```\n\nDestroy a Pittacus descriptor:\n```cpp\npittacus_gossip_destroy(gossip);\n```\n\nFor a more complete examples check out the `demos/demo_node.c` and `demos/demo_seed_node.c` demo applications. Both demo applications will be built automatically together with the library code.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizeigerman%2Fpittacus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fizeigerman%2Fpittacus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fizeigerman%2Fpittacus/lists"}