lo_serverthread.h(3)

📦
version 0.34 · 3 versions
, in fedora 44

✨ lo_serverthread.h(3) ✨

okay bestie, sit down, hydrate, and let's talk about lo_serverthread.h(3) — the liblo manual page that's literally all about threads and it's giving main character energy. 🧵💖

🌸 NAME 🌸

lo_serverthread.h

that's it, that's the name, short and iconic 🎀

🦋 SYNOPSIS 🦋

✨ Functions ✨

bestie, this is the whole roster. every single one, no skips, no cap. 💅

🫶 lo_server_thread_new

lo_server_thread lo_server_thread_new (const char *port, lo_err_handler err_h)

Spin up a brand new server thread that catches all your incoming OSC messages. Your lil inbox for OSC, basically. ✨

🌈 lo_server_thread_new_multicast

lo_server_thread lo_server_thread_new_multicast (const char *group, const char *port, lo_err_handler err_h)

Same deal — a new server thread handling incoming OSC messages — but this one also joins a UDP multicast group. It's a group chat. Literally. 👑

🦋 lo_server_thread_new_multicast_iface

lo_server_thread lo_server_thread_new_multicast_iface (const char *group, const char *port, const char *iface, const char *ip, lo_err_handler err_h)

Make a new server thread instance AND join a UDP multicast group, with the option to say which network interface to use. Quick note bestie: usually you only set one of iface or ip, not both. Pick a lane, she's not greedy. 🙈

⭐ lo_server_thread_new_with_proto

lo_server_thread lo_server_thread_new_with_proto (const char *port, int proto, lo_err_handler err_h)

New server thread for incoming OSC messages, except this time you get to specify the protocol yourself. Choose your own adventure. 🔥

💜 lo_server_thread_new_from_url

lo_server_thread lo_server_thread_new_from_url (const char *url, lo_err_handler err_h)

Builds a new server thread by pulling the port — and the optional multicast group IP — straight out of a URL string. It's the "just read it off the link" moment. 🎀

🌸 lo_server_thread_new_from_config

lo_server_thread lo_server_thread_new_from_config (lo_server_config *config)

New server thread, but sourced from a configuration struct. Fancy. Structured. Organized queen behavior. ✨

💀 lo_server_thread_free

void lo_server_thread_free (lo_server_thread st)

Releases the memory that a server thread was hogging. Give her back to the void. 🦋

🎀 lo_server_thread_add_method

lo_method lo_server_thread_add_method (lo_server_thread st, const char *path, const char *typespec, lo_method_handler h, const void *user_data)

Adds an OSC method to the specified server thread. New method, who dis. 💖

🌟 lo_server_thread_del_method

void lo_server_thread_del_method (lo_server_thread st, const char *path, const char *typespec)

Deletes an OSC method from the specified server thread. Bye bestie, it's not personal. 👋

🔥 lo_server_thread_del_lo_method

int lo_server_thread_del_lo_method (lo_server_thread st, lo_method m)

Also deletes an OSC method from the specified server thread, but this one takes the method itself instead of a path and typespec. Same energy, different doorway. ✨

🧚 lo_server_thread_set_callbacks

void lo_server_thread_set_callbacks (lo_server_thread st, lo_server_thread_init_callback init, lo_server_thread_cleanup_callback cleanup, void *user_data)

Hooks up an init and/or a cleanup function to the specified server thread. Setting the vibe for when she starts and when she says goodnight. 🌸

👑 lo_server_thread_start

int lo_server_thread_start (lo_server_thread st)

Starts the server thread. Go girl, go. 🚀

🌙 lo_server_thread_stop

int lo_server_thread_stop (lo_server_thread st)

Stops the server thread. Nap time, deserved. 💤

⭐ lo_server_thread_get_port

int lo_server_thread_get_port (lo_server_thread st)

Hands you back the port number the server thread has bound to. "What port are you on" but she actually answers. 🎀

🌈 lo_server_thread_get_url

char * lo_server_thread_get_url (lo_server_thread st)

Returns a URL that describes the address of the server thread. Her little business card. 💌

💜 lo_server_thread_get_server

lo_server lo_server_thread_get_server (lo_server_thread st)

Gives you the lo_server sitting inside a lo_server_thread. The thread's inner self, exposed. 🦋

✨ lo_server_thread_events_pending

int lo_server_thread_events_pending (lo_server_thread st)

Returns true if there are scheduled events (like, from bundles) just waiting for the thread to dispatch them. The "you have unread messages" of OSC. 💬

💅 lo_server_thread_pp

void lo_server_thread_pp (lo_server_thread st)

Pretty-prints a lo_server_thread object. Glow-up for your eyeballs, no notes. 🌟

👑 Detailed Description 👑

The liblo headerfile declaring thread-related functions. That's the whole vibe: it's the header that announces all the thread stuff. 🧵💖

Definition in file lo_serverthread.h. 🌸

and bestie… there's literally more 👀

🧚 FUNCTION DOCUMENTATION 🧚

okay bestie, this is the part where we meet every single function in lo_serverthread.h one by one, no skipping, no skimming, we're reading the whole menu 💅 each one gets its own lil spotlight, its signature, its params, its returns, all of it. let's gooo 🦋

💖 lo_method lo_server_thread_add_method (lo_server_thread st, const char * path, const char * typespec, lo_method_handler h, const void * user_data)

Add an OSC method to the specifed server thread. this is the "hey server, when a message like this shows up, run this" move ✨

Parameters

  • st — the server thread the method is to be added to.
  • path — the OSC path to register the method to. if NULL is passed, the method will match all paths. literally all of them, she's for everybody 🫶
  • typespec — the typespec the method accepts. incoming messages with similar typespecs (e.g. ones with numerical types in the same position) will be coerced to the typespec given here. so she'll meet you where you're at, type-wise.
  • h — the method handler callback function that will be called it a matching message is received.
  • user_data — a value that will be passed to the callback function, h, when its invoked matching from this method.

🌸 int lo_server_thread_del_lo_method (lo_server_thread st, lo_method m)

Delete an OSC method from the specified server thread. bye bestie 👋

Parameters

  • st — the server thread the method is to be removed from.
  • m — the lo_method identifier returned from lo_server_add_method for the method to delete from the server.

Returns

Non-zero if it was not found in the list of methods for the server.

🎀 void lo_server_thread_del_method (lo_server_thread st, const char * path, const char * typespec)

Delete an OSC method from the specifed server thread — this time you point at it by path + typespec instead of by handle.

Parameters

  • st — the server thread the method is to be removed from.
  • path — the OSC path of the method to delete. if NULL is passed the method will match the generic handler.
  • typespec — the typespec the method accepts.

🦋 int lo_server_thread_events_pending (lo_server_thread st)

Return true if there are scheduled events (eg. from bundles) waiting to be dispatched by the thread. yes queen, the queue is not empty, something's coming 👀

💜 void lo_server_thread_free (lo_server_thread st)

Free memory taken by a server thread. frees the memory, and, if currently running will stop the associated thread. so it's not just a clean-up, it will shut her down too. no cap.

⭐ int lo_server_thread_get_port (lo_server_thread st)

Return the port number that the server thread has bound to. the receipts, basically 🧾

🌈 lo_server lo_server_thread_get_server (lo_server_thread st)

Return the lo_server for a lo_server_thread. this function is useful for passing a thread's lo_server to lo_send_from(). iykyk 💫

🍓 char * lo_server_thread_get_url (lo_server_thread st)

Return a URL describing the address of the server thread.

bestie listen: the return value must be free()'d to reclaim memory. she's not gonna do it for you. free her or leak her, your call 😭

👑 lo_server_thread lo_server_thread_new (const char * port, lo_err_handler err_h)

Create a new server thread to handle incoming OSC messages. server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. use this if you do not want to handle the threading yourself — she's got it, main character energy fr fr 💅

Parameters

  • port — if NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. otherwise a decimal port number, service name or UNIX domain socket path may be passed.
  • err_h — a function that will be called in the event of an error being raised. the function prototype is defined in lo_types.h.

🧚 lo_server_thread lo_server_thread_new_from_config (lo_server_config * config)

Create a new server thread, using a configuration struct. plug-and-play era ✨

Parameters

  • config — a pre-initialized config struct. a pointer to it will not be kept.

Returns

A new lo_server_thread instance.

🔥 lo_server_thread lo_server_thread_new_from_url (const char * url, lo_err_handler err_h)

Create a new server thread, taking port and the optional multicast group IP from an URL string. very demure, very URL 💖

Parameters

  • url — the URL to specify the server parameters.
  • err_h — an error callback function that will be called if there is an error in messge reception or server creation. pass NULL if you do not want error handling.

Returns

A new lo_server_thread instance.

💀 lo_server_thread lo_server_thread_new_multicast (const char * group, const char * port, lo_err_handler err_h)

Create a new server thread to handle incoming OSC messages, and join a UDP multicast group. server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. use this if you do not want to handle the threading yourself.

Parameters

  • group — the multicast group to join. see documentation on IP multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html
  • port — if NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. otherwise a decimal port number, service name or UNIX domain socket path may be passed.
  • err_h — a function that will be called in the event of an error being raised. the function prototype is defined in lo_types.h.

🙈 lo_server_thread lo_server_thread_new_multicast_iface (const char * group, const char * port, const char * iface, const char * ip, lo_err_handler err_h)

Create a new server thread instance, and join a UDP multicast group, optionally specifying which network interface to use.

note: usually only one of iface or ip are specified. not both, bestie, pick a lane 🌸

Parameters

  • group — the multicast group to join. see documentation on IP multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html
  • port — if using UDP then NULL may be passed to find an unused port. otherwise a decimal port number or service name or may be passed. if using UNIX domain sockets then a socket path should be passed here.
  • iface — a string specifying the name of a network interface to use, or zero if not specified.
  • ip — a string specifying the IP address of a network interface to use, or zero if not specified.
  • err_h — an error callback function that will be called if there is an error in messge reception or server creation. pass NULL if you do not want error handling.

🎀 lo_server_thread lo_server_thread_new_with_proto (const char * port, int proto, lo_err_handler err_h)

Create a new server thread to handle incoming OSC messages, specifying protocol. server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. use this if you do not want to handle the threading yourself.

Parameters

  • port — if NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. otherwise a decimal port number, service name or UNIX domain socket path may be passed.
  • proto — the protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX.
  • err_h — a function that will be called in the event of an error being raised. the function prototype is defined in lo_types.h.

🫶 void lo_server_thread_pp (lo_server_thread st)

Pretty-print a lo_server_thread object. she said "let me look cute for the terminal" 💅

✨ void lo_server_thread_set_callbacks (lo_server_thread st, lo_server_thread_init_callback init, lo_server_thread_cleanup_callback cleanup, void * user_data)

Set an init and/or a cleanup function to the specifed server thread.

⚠️ to have any effect, it must be called before the server thread is started. timing is everything, bestie, no exceptions.

Parameters

  • st — the server thread to which the method is to be added.
  • init — the init function to be called just after thread start. may be NULL.
  • cleanup — the cleanup function to be called just before thread exit. may be NULL.
  • user_data — a value that will be passed to the callback functions.

🌟 int lo_server_thread_start (lo_server_thread st)

Start the server thread. go girl, go 🚀

Parameters

  • st — the server thread to start.

Returns

Less than 0 on failure, 0 on success.

🛑 int lo_server_thread_stop (lo_server_thread st)

Stop the server thread. that's a wrap, periodt.

Parameters

  • st — the server thread to start.

Returns

Less than 0 on failure, 0 on success.

💌 AUTHOR 💌

Generated automatically by Doxygen for liblo from the source code. (not me, i just added the sparkle 💖)

and that's the whole page, bestie!! 🎉 this whole thing is liblo, Version 0.34, from lo_serverthread.h(3). go forth and thread your OSC servers responsibly, mwah 😘🦋✨

📦 where this page comes from