TCLCURL_MULTI(3tcl)

📦
version 8.0.3 · 2 versions
, in ubuntu stonking

💖 TclCurl Multi Interface — the group project where EVERYONE transfers at once 💖

okay so bestie, this is the manual page for the TclCurl Multi Interface, living in the TclCurl Easy Interface corner of the TclCurl Multi Interface(n) section. yes the title is a little redundant, she contains multitudes, we move. 💅

✨ NAME ✨

TclCurl — do a whole bunch of URL transfers at the SAME TIME with the TclCurl multi interface. not one, not two, a stack. no cap. 🔥

🌸 SYNOPSIS 🌸

curl::multiinit
curl::multistrerror errorCode

multiHandle addhandle
multiHandle removehandle
multiHandle configure
multiHandle perform
multiHandle active
multiHandle getinfo
multiHandle cleanup
multiHandle auto ?-command command?

🦋 DESCRIPTION 🦋

so TclCurl's multi interface is not doing the same thing as the easy interface, and honestly she's proud of it. she's specifically built to:

  • give you a "pull" interface, which is a fancy way of saying your application decides when and how the data transfers actually get driven 👑
  • support multiple simultaneous transfers inside the same thread. iconic. multitasking queen. ✨
  • let Tk applications stay responsive while transfers are happening, so your GUI doesn't just freeze and stare at you like 😭

💀 BLOCKING 💀

heads up bestie: some operations are STILL blocking even when you're using the multi interface. it's giving "we're not fully async yet" and you need to know about it. these are the current limitations:
  • Name resolution on non-Windows systems — unless c-ares is being used
  • GnuTLS SSL connections
  • Active FTP connections
  • HTTP proxy CONNECT operations
  • SOCKS proxy handshakes
  • file:// transfers
  • TELNET transfers

🎀 curl::multiinit 🎀

this one has to be called FIRST, periodt. it hands you back a multiHandle, and that's the key you use to invoke all the TclCurl multi-interface procedures. every single call to multiinit MUST have a matching call to cleanup when the whole operation is done. no ghost handles, we don't do that here. 🫶

🌟 RETURN VALUE 🌟

the multiHandle you're gonna use. that's it, that's the gift. 💖

🌈 multiHandle addhandle ?easyHandle? 🌈

each individual transfer is represented by an easy handle. so the vibe is: you create the easy handle, you configure it with whatever options it needs, and then you add it to the multi stack with the addhandle command. build her up, then send her out. ✨

if the easy handle isn't configured to use a shared or global DNS cache, it'll use the DNS cache that's shared by all the easy handles hanging out with the same multi handle. found family DNS. 🦋

⚠️ once an easy handle has been added to a multi stack, you must not call perform on that easy handle directly. don't do it. she has a new team now.

multiHandle is the value that came back from the curl::multiinit call.

🌟 RETURN VALUE 🌟

possible return values, and what they mean:

  • -1 — the handle was added to the multi stack. call perform soon. like, soon soon. 👀
  • 0 — it got added successfully, we love a happy ending 🎉
  • 1 — invalid multi handle
  • 2 — invalid easy handle. this can mean it's not an easy handle at all, or that it's already in use by this multi handle or by another one. she's taken 💅
  • 3 — out of memory
  • 4 — you found a bug in TclCurl 🐛 (congrats? sorry?)

🧚 multiHandle removehandle ?easyHandle? 🧚

when a transfer is complete, or when you wanna stop a transfer before it's complete, you use the removehandle command. once she's removed from the multi handle, the easy handle can be used again with other easy-interface operations. free agent era. 🔥

note: when a transfer completes, the easy handle stays associated with the multi stack. you have to remove it explicitly before cleaning it up, or before reconfiguring it and adding it back to the multi handle for another transfer. she doesn't leave on her own, you have to actually tell her.

🌟 RETURN VALUE 🌟

possible return values, bestie:

  • 0 — the handle was removed successfully ✅
  • 1 — invalid multi handle
  • 2 — invalid easy handle
  • 3 — out of memory
  • 4 — you found a bug in TclCurl 🐛

💅 multiHandle configure 💅

so far the only options are these two. short list, but she's got range:

  • -pipelining — pass 1 to enable this option or 0 to disable it. when it's enabled, TclCurl will attempt to use HTTP pipelining where it can for the transfers associated with this multi handle. in practice, if you add a second request that can reuse an existing connection, that request may be sent on the same connection instead of being executed in parallel on a separate one. sharing is caring, connections edition ✨
  • -maxconnects — pass a number and it becomes the maximum amount of simultaneously open connections that TclCurl may cache. the default is 10. TclCurl may enlarge the cache so it can hold up to four times the number of easy handles added to the multi handle. by setting this option, you can stop the cache size from growing beyond the limit you set. when the cache is full, curl closes the oldest one in the cache so the number of open connections doesn't keep increasing. this option applies only to multi handles — if you're using the easy interface, use the easy handle's own maxconnects option instead. 👑

⭐ multiHandle perform ⭐

adding easy handles to the multi stack does NOT start any transfer. nope. one of the main purposes of the multi interface is to let the application drive the transfers explicitly — and you do that by invoking perform. you're the driver, she's the car. 🚗

when perform is called, TclCurl advances the transfers for the easy handles in the multi stack that are currently ready for I/O. as data gets sent or received, TclCurl may invoke the callbacks configured on the individual easy handles — like read, write, progress, header, or debug callbacks — according to the state of each transfer. depending on the state of things, this might involve all the handles, some of them, or literally none. vibe check pending. 🫶

if, after a call to perform, the number of running handles has changed from the previous call, or is lower than the number of easy handles added to the multi handle, that means one or more transfers are no longer running. in that case you can call getinfo to get info about each completed transfer. and lowkey? if an added handle fails very quickly, it may never even get counted as running. she came and went. 💀

🌟 RETURN VALUE 🌟

if everything goes well, this command returns the number of running handles, or 0 if all the transfers are complete. if there's an error, it returns the error code.

and important: this command reports only errors related to the multi stack as a whole. individual transfers may still have failed even when perform itself returns successfully. so don't get cocky just because the return value looked pretty. 🙈

🌸 multiHandle active 🌸

use the active command to figure out whether any of the easy handles are currently ready to transfer data before you invoke perform. it returns the number of transfers that are currently active. little pre-flight check, so cute. ✨

🌟 RETURN VALUE 🌟

the number of active transfers, or -1 if there's an error.

🔮 multiHandle getinfo 🔮

this procedure returns a small amount of information about transfers in the multi stack. for more detailed info, go use the getinfo command on the individual easy handles. this one's the trailer, not the whole movie. 🎬

🌟 RETURN VALUE 🌟

a list with these elements, in this order:

  1. the easyHandle the information applies to
  2. the state of the transfer — 1 if it is complete
  3. the transfer exit code — 0 if no error occurred
  4. the number of messages still in the info queue

if there are no messages in the queue, this command returns {"" 0 0 0}. empty queue, empty vibes, still valid. 💜

🫶 multiHandle cleanup 🫶

this procedure must be the last one called for a multi stack. she's the counterpart of curl::multiinit, and you have to call her with the exact same multiHandle that curl::multiinit returned. close the loop, bestie. 🔁

👑 multiHandle auto ?-command command? 👑

with this command, Tcl's event loop takes care of periodically invoking perform for you. you don't have to lift a finger, she's got it. 💅

but before you use it, you must already have added at least one easy handle to the multi handle. no handles, no party. 🎉

the -command option lets you specify a command to invoke after all easy handles have finished their transfers. in practice, you should use this command to do the necessary cleanup of the handles. otherwise, the transferred files may not be complete. seriously, do the cleanup. 😭

🌈 this support is still experimental and may change without warning. she's in her ✨figuring herself out✨ era.

you can find a couple of examples at tests/multi.

🍓 curl::multistrerror errorCode 🍓

this procedure returns a string describing the error code that was passed in the argument. basically it translates cryptic number into real words, which is a public service honestly. 🌟

💖 SEE ALSO 💖

  • TclCurl
  • curl

and that's the whole page, bestie!! 🦋 go forth and transfer many things simultaneously, you absolute icon. 🎀

this was TclCurl 8.0.3, dated 19-05-2026, from the TclCurl Multi Interface(n) manual — mwah, ilysm, now go cleanup your handles 💋💖

📦 where this page comes from